Python 办公

对比Excel数据透视表，学习pandas pivot_table

2021年5月6日 Python实用宝典

Excel的数据透视表非常有用，但是Pandas也有这个功能你知道吗？今天我们来对比Excel数据透视表，学习pandas pivot_table

1.Excel中做数据透视表

① 选中整个数据源；

② 依次点击“插入”—“数据透视表”

③ 选择在Excel中的哪个位置，插入数据透视表

④ 然后根据实际需求，从不同维度展示结果

⑤ 结果如下

2. pandas 用 pivot_table 做数据透视表

1）语法格式

pd.pivot_table(data,index=None,columns=None,
               values=None,aggfunc='mean',
               margins=False,margins_name='All',
               dropna=True,fill_value=None)

2）对比excel，说明上述参数的具体含义

参数说明：

data 相当于Excel中的”选中数据源”；
index 相当于上述”数据透视表字段”中的行；
columns 相当于上述”数据透视表字段”中的列；
values 相当于上述”数据透视表字段”中的值；
aggfunc 相当于上述”结果”中的计算类型；
margins 相当于上述”结果”中的总计；
margins_name 相当于修改”总计”名，为其它名称；

下面几个参数，用的较少，记住干嘛的，等以后需要就百度。

dropna 表示是否删除缺失值，如果为True时，则把一整行全作为缺失值删除；
fill_value 表示将缺失值，用某个指定值填充。

3. 案例说明

1）求出不同品牌下，每个月份的销售数量之和

① 在Excel中的操作结果如下

② 在pandas中的操作如下

df = pd.read_excel(r"C:\Users\黄伟\Desktop\pivot_table.xlsx")
display(df.sample(5))

df.insert(1,"月份",df["销售日期"].apply(lambda x:x.month))
display(df.sample(5))

df1 = pd.pivot_table(df,index="品牌",columns="月份",
                     values="销售数量",aggfunc=np.sum)
display(df1)

结果如下：

2）求出不同品牌下，每个地区、每个月份的销售数量之和

① 在Excel中的操作结果如下

② 在pandas中的操作如下

df = pd.read_excel(r"C:\Users\黄伟\Desktop\pivot_table.xlsx")
display(df.sample(5))

df.insert(1,"月份",df["销售日期"].apply(lambda x:x.month))
display(df.sample(5))

df1 = pd.pivot_table(df,index="品牌",columns=["销售区域","月份"],
                     values="销售数量",aggfunc=np.sum)
display(df1)

结果如下：

3）求出不同品牌不同地区下，每个月份的销售数量之和

① 在Excel中的操作结果如下

② 在pandas中的操作如下

df = pd.read_excel(r"C:\Users\黄伟\Desktop\pivot_table.xlsx")
display(df.sample(5))

df.insert(1,"月份",df["销售日期"].apply(lambda x:x.month))
display(df.sample(5))

df1 = pd.pivot_table(df,index=["品牌","销售区域"],columns="月份",
                     values="销售数量",aggfunc=np.sum)
display(df1)

结果如下：

4）求出不同品牌下的“销售数量之和”与“货号计数”

① 在Excel中的操作结果如下

② 在pandas中的操作如下

df = pd.read_excel(r"C:\Users\黄伟\Desktop\pivot_table.xlsx")
display(df.sample(5))

df.insert(1,"月份",df["销售日期"].apply(lambda x:x.month))
display(df.sample(5))

df1 = pd.pivot_table(df,index="品牌",columns="月份",
                     values=["销售数量","货号"],
                     aggfunc={"销售数量":"sum","货号":"count"},
                     margins=True,margins_name="总计")
display(df1)

结果如下：

本文转自凹凸数据。

我们的文章到此就结束啦，如果你喜欢今天的Python 实战教程，请持续关注Python实用宝典。

有任何问题，可以在公众号后台回复：加群，回答相应红字验证信息，进入互助群询问。

原创不易，希望你能在下面点个赞和在看支持我继续创作，谢谢！

点击下方阅读原文可获得更好的阅读体验

Python实用宝典 (pythondict.com)
不只是一个宝典
欢迎关注公众号：Python实用宝典

安全、工具、开发工具、解决方案

Python 调用 Shodan 实战教程 — 互联网上最可怕的搜索引擎

2021年5月4日 Python实用宝典留下评论

Shodan 在百度百科里被给出了这么一句话介绍：Shodan是互联网上最可怕的搜索引擎。

为什么呢？与谷歌、百度等搜索引擎爬取网页信息不同，Shodan爬取的是互联网上所有设备的IP地址及其端口号。

而随着智能家电的普及，家家户户都有许多电器连接到互联网，这些设备存在被入侵的可能性，这是十分危险的。

说了这么多，给大家体验下shodan，让你们有更切身的理解。打开shodan，在搜索框输入 Hikvision-Webs:

你会搜素到这个品牌的摄像头设备遍及全球的IP及其暴露的端口号：

可以看到，这台机器暴露了17、80、111、995、3128、5000、6000、20547端口，黑客可以根据这些端口进行针对性的攻击。

不过也不需要过于担心，如果你的服务不存在漏洞，一般是无法攻入的。但有些端口号会暴露摄像头的web管理端，如下：

那么黑客可能可以用暴力破解的方式，强行进入摄像头后台管理端，获取到实时的录像。

谨记这会侵犯别人的隐私权，是违法的行为，我们是遵纪守法的好公民所以知道它的原理和危害就足够。我们的目的是运用技术保护好个人隐私，如非必要不将摄像头接入互联网，一定要接入的话，不能使用容易被破解的弱口令。

Shodan Web端非常好用，但如果我们有从Python搜索的需求怎么办？

没关系，shodan 官方也提供了python官方SDK包，下面就来讲讲这个SDK包的使用。

1.准备

开始之前，你要确保Python和pip已经成功安装在电脑上，如果没有，请访问这篇文章：超详细Python安装指南进行安装。

(可选1) 如果你用Python的目的是数据分析，可以直接安装Anaconda：Python数据分析与挖掘好帮手—Anaconda，它内置了Python和pip.

(可选2) 此外，推荐大家用VSCode编辑器来编写小型Python项目：Python 编程的最好搭档—VSCode 详细指南

Windows环境下打开Cmd(开始—运行—CMD)，苹果系统环境下请打开Terminal(command+空格输入Terminal)，输入命令安装依赖：

pip install shodan

2.Shodan 注册账号获取API

使用 Shodan 必须注册账号，注册网址：https://account.shodan.io/register

输入完相关信息，点击 CREATE 会跳转到个人账户页：

此时 API Key 会显示你的API秘钥，请记录这个秘钥，后续会使用到这个秘钥去请求接口。

3.Shodan 基本调用实战教程

Shodan本质上就是一个搜索引擎，你只需要输入搜索的关键词：

# 公众号：Python 实用宝典
# 2021-05-04
from shodan import Shodan

api = Shodan('你的API KEY')

def search_shodan(keyword):
    # 调用搜索接口
    result = api.search(keyword)

    # 显示所有IP
    for service in result['matches']:
            print(service['ip_str'])

search_shodan("Hikvision-Webs")

结果如下：

可惜的是，普通API只能像这样搜索关键字，无法使用过滤条件如：Hikvision-Webs country:”US” 搜索美国内的所有Hikvision网站管理端。

如果你想要使用过滤条件，Shodan需要你升级API权限：

挺贵的，不过还好是一次性支付，永久使用。

4. Shodan 高级使用教程

Shodan 的用处当然不仅仅是在黑客攻防中，它还能用于统计。如果你想要了解哪些国家的使用这款摄像头的数量最多，可以使用 Facets 特性。

# 公众号：Python 实用宝典
# 2021-05-04
from shodan import Shodan

api = Shodan('你的API KEY')
def try_facets(query):
    FACETS = [
        'org',
        'domain',
        'port',
        'asn',
        ('country', 3),
    ]

    FACET_TITLES = {
        'org': 'Top 5 Organizations',
        'domain': 'Top 5 Domains',
        'port': 'Top 5 Ports',
        'asn': 'Top 5 Autonomous Systems',
        'country': 'Top 3 Countries',
    }

    try:
        # 使用 count() 方法可以不需要升级API，且比 search 方法更快。
        result = api.count(query, facets=FACETS)

        print('Shodan Summary Information')
        print('Query: %s' % query)
        print('Total Results: %s\n' % result['total'])

        # 显示每个要素的摘要
        for facet in result['facets']:
            print(FACET_TITLES[facet])

            for term in result['facets'][facet]:
                print('%s: %s' % (term['value'], term['count']))

    except Exception as e:
        print('Error: %s' % e)

try_facets("Hikvision-Webs")

得到结果如下：

从 Top 3 Countries 中可以看到，这款摄像头使用数量排名前三的国家分别是：美国、日本和德国。

没想到吧，Shodan居然还能用于产品分析。同样地原理，如果你把关键词改为”apache”，你可以知道目前哪些国家使用apache服务器数量最多，最普遍被使用的版本号是什么。

简而言之，Shodan是一个非常强大的搜索引擎，它在好人手里，能被发挥出巨大的潜能。如果Shodan落入坏人之手的话，那真是一个可怕的东西。

为了避免受到不必要的攻击，请大家及时检查所有联网设备的管理端的密码，如果有使用默认密码及弱口令，立即进行密码的更改，以保证服务的安全。

本文所有源代码可在 Python 实用宝典公众号后台回复：shodan 下载。

我们的文章到此就结束啦，如果你喜欢今天的 Python 教程，请持续关注Python实用宝典。

有任何问题，可以在公众号后台回复：加群，回答相应验证信息，进入互助群询问。

原创不易，希望你能在下面点个赞和在看支持我继续创作，谢谢！

我要打赏

Python实用宝典 ( pythondict.com )
不只是一个宝典
欢迎关注公众号：Python实用宝典

Python 爬虫

Python 新型的爬虫框架 feapder, 支持爬虫报警机制

2021年5月4日 Python实用宝典

1. 前言

众所周知，Python 最流行的爬虫框架是 Scrapy，它主要用于爬取网站结构性数据

今天推荐一款更加简单、轻量级，且功能强大的爬虫框架：feapder

项目地址：

https://github.com/Boris-code/feapder

2. 介绍及安装

和 Scrapy 类似，feapder 支持轻量级爬虫、分布式爬虫、批次爬虫、爬虫报警机制等功能

内置的 3 种爬虫如下：

AirSpider

轻量级爬虫，适合简单场景、数据量少的爬虫
Spider

分布式爬虫，基于 Redis，适用于海量数据，并且支持断点续爬、自动数据入库等功能
BatchSpider

分布式批次爬虫，主要用于需要周期性采集的爬虫

在实战之前，我们在虚拟环境下安装对应的依赖库

# 安装依赖库
pip3 install feapder

3. 实战一下

我们以最简单的 AirSpider 来爬取一些简单的数据

目标网站：aHR0cHM6Ly90b3BodWIudG9kYXkvIA==

详细实现步骤如下（ 5 步）

3-1 创建爬虫项目

首先，我们使用「 feapder create -p 」命令创建一个爬虫项目

# 创建一个爬虫项目
feapder create -p tophub_demo

3-2 创建爬虫 AirSpider

命令行进入到 spiders 文件夹目录下，使用「 feapder create -s 」命令创建一个爬虫

cd spiders

# 创建一个轻量级爬虫
feapder create -s tophub_spider 1

其中

1 为默认，表示创建一个轻量级爬虫 AirSpider
2 代表创建一个分布式爬虫 Spider
3 代表创建一个分布式批次爬虫 BatchSpider

3-3 配置数据库、创建数据表、创建映射 Item

以 Mysql 为例，首先我们在数据库中创建一张数据表

# 创建一张数据表
create table topic
(
    id         int auto_increment
        primary key,
    title      varchar(100)  null comment '文章标题',
    auth       varchar(20)   null comment '作者',
    like_count     int default 0 null comment '喜欢数',
    collection int default 0 null comment '收藏数',
    comment    int default 0 null comment '评论数'
);

然后，打开项目根目录下的 settings.py 文件，配置数据库连接信息

# settings.py

MYSQL_IP = "localhost"
MYSQL_PORT = 3306
MYSQL_DB = "xag"
MYSQL_USER_NAME = "root"
MYSQL_USER_PASS = "root"

最后，创建映射 Item（可选）

进入到 items 文件夹，使用「 feapder create -i 」命令创建一个文件映射到数据库

PS：由于 AirSpider 不支持数据自动入库，所以这步不是必须

3-4 编写爬虫及数据解析

第一步，首先使「 MysqlDB 」初始化数据库

from feapder.db.mysqldb import MysqlDB

class TophubSpider(feapder.AirSpider):

    def __init__(self, *args, **kwargs):
        super().__init__(*args, **kwargs)
        self.db = MysqlDB()

第二步，在 start_requests 方法中，指定爬取主链接地址，使用关键字「download_midware 」配置随机 UA

import feapder
from fake_useragent import UserAgent

def start_requests(self):
    yield feapder.Request("https://tophub.today/", download_midware=self.download_midware)

def download_midware(self, request):
    # 随机UA
    # 依赖：pip3 install fake_useragent
    ua = UserAgent().random
    request.headers = {'User-Agent': ua}
    return request

第三步，爬取首页标题、链接地址

使用 feapder 内置方法 xpath 去解析数据即可

def parse(self, request, response):
    # print(response.text)
    card_elements = response.xpath('//div[@class="cc-cd"]')

    # 过滤出对应的卡片元素【什么值得买】
    buy_good_element = [card_element for card_element in card_elements if
                        card_element.xpath('.//div[@class="cc-cd-is"]//span/text()').extract_first() == '什么值得买'][0]

    # 获取内部文章标题及地址
    a_elements = buy_good_element.xpath('.//div[@class="cc-cd-cb nano"]//a')

    for a_element in a_elements:
        # 标题和链接
        title = a_element.xpath('.//span[@class="t"]/text()').extract_first()
        href = a_element.xpath('.//@href').extract_first()

        # 再次下发新任务，并带上文章标题
        yield feapder.Request(href, download_midware=self.download_midware, callback=self.parser_detail_page,
                              title=title)

第四步，爬取详情页面数据

上一步下发新的任务，通过关键字「 callback 」指定回调函数，最后在 parser_detail_page 中对详情页面进行数据解析

def parser_detail_page(self, request, response):
    """
    解析文章详情数据
    :param request:
    :param response:
    :return:
    """
    title = request.title

    url = request.url

    # 解析文章详情页面，获取点赞、收藏、评论数目及作者名称
    author = response.xpath('//a[@class="author-title"]/text()').extract_first().strip()

    print("作者：", author, '文章标题:', title, "地址：", url)

    desc_elements = response.xpath('//span[@class="xilie"]/span')

    print("desc数目:", len(desc_elements))

    # 点赞
    like_count = int(re.findall('\d+', desc_elements[1].xpath('./text()').extract_first())[0])
    # 收藏
    collection_count = int(re.findall('\d+', desc_elements[2].xpath('./text()').extract_first())[0])
    # 评论
    comment_count = int(re.findall('\d+', desc_elements[3].xpath('./text()').extract_first())[0])

    print("点赞：", like_count, "收藏:", collection_count, "评论:", comment_count)

3-5 数据入库

使用上面实例化的数据库对象执行 SQL，将数据插入到数据库中即可

# 插入数据库
sql = "INSERT INTO topic(title,auth,like_count,collection,comment) values('%s','%s','%s','%d','%d')" % (
title, author, like_count, collection_count, comment_count)

# 执行
self.db.execute(sql)

4. 最后

本篇文章通过一个简单的实例，聊到了 feapder 中最简单的爬虫 AirSpider

关于 feapder 高级功能的使用，后面我将会通过一系列实例进行详细说明

如果你觉得文章还不错，请大家 点赞、分享、留言 下，因为这将是我持续输出更多优质文章的最强动力！

我们的文章到此就结束啦，如果你喜欢今天的 Python 教程，请持续关注Python实用宝典。

有任何问题，可以在公众号后台回复：加群，回答相应验证信息，进入互助群询问。

原创不易，希望你能在下面点个赞和在看支持我继续创作，谢谢！

我要打赏

Python实用宝典 ( pythondict.com )
不只是一个宝典
欢迎关注公众号：Python实用宝典

开发工具、性能优化、测试

Python 性能测试工具 Locust 极简入门

2021年5月3日 Python实用宝典

作者：dongfanger

来源：dongfanger

Locust是一款Python技术栈的开源的性能测试工具。Locust直译为蝗虫，寓意着它能产生蝗虫般成千上万的并发用户：

Locust并不小众，从它Github的Star数量就可见一斑：

截止文章写作时，一共15951Star。

Locust生态良好，它已在多家外企（包括世界500强）投入使用：

如此看来，Locust是非常值得学习和掌握的一款工具。

Python的魔力在于化繁为简，基于Python的Locust也能给仍然困惑于性能测试的我们带来启发。

1.Locust特点

以纯Python方式编写用户脚本，提供极大自由度。
用户脚本可以串行方式编写，Locust会通过轻量级进程/协程产生并发，无需自己做并发编程。
并发量大，借助于gevent库，Locust能产生成千上万并发请求。
开销小，Locust用户运行时开销很小。
良好的Web UI对性能结果实时监测。
能测任何系统任何协议，只需要写个client即可。
开放REST API，尽情发挥。

2.安装Locust

需要Python版本3.6及以上。

执行pip命令：

$ pip install locust

验证安装成功：

$ locust -V

安装时会一并安装依赖库：

Installing collected packages: Werkzeug, pywin32, zope.event, greenlet, gevent, geventhttpclient, itsdangerous, flask, Flask-BasicAuth, ConfigArgParse, pyzmq, psutil, locust

能看出来flask为Locust提供了Web功能。

3.快速上手

使用Locust一般按照以下步骤进行：

编写Python用户脚本。
使用locust命令执行性能测试。
（可选）通过Web界面监测结果。

示例代码如下，新建locustfile.py文件：

import time
from locust import HttpUser, task, between

class QuickstartUser(HttpUser):
wait_time = between(1, 2.5)

@task
def hello_world(self):
self.client.get(“/hello”)
self.client.get(“/world”)

@task(3)
def view_items(self):
for item_id in range(10):
self.client.get(f”/item?id={item_id}“, name=“/item”)
time.sleep(1)

def on_start(self):
self.client.post(“/login”, json={“username”:“foo”, “password”:“bar”})

路径切换到locustfile.py文件所在目录，执行命令：

$ locust

也可以通过-f指定某个目录文件：

$ locust -f locust_files/my_locust_file.py

运行后，打开http://127.0.0.1:8089看到Web界面：

填写信息后，就能开始压测了。Web界面提供了结果统计数据：

和性能指标走势图：

4.脚本解析

示例脚本解析如下：

# Locust用户脚本就是Python模块
import time
from locust import HttpUser, task, between

# 类继承自HttpUser
class QuickstartUser(HttpUser):
# 每个模拟用户等待1~2.5秒
wait_time = between(1, 2.5)

# 被@task装饰的才会并发执行
@task
def hello_world(self):
# client属性是HttpSession实例，用来发送HTTP请求
self.client.get(“/hello”)
self.client.get(“/world”)

# 每个类只会有一个task被选中执行
# 3代表weight权重
# 权重越大越容易被选中执行
# view_items比hello_wolrd多3倍概率被选中执行
@task(3)
def view_items(self):
for item_id in range(10):
# name参数作用是把统计结果按同一名称进行分组
# 这里防止URL参数不同会产生10个不同记录不便于观察
# 把10个汇总成1个”/item”记录
self.client.get(f”/item?id={item_id}“, name=“/item”)
time.sleep(1)

# 每个模拟用户开始运行时都会执行
def on_start(self):
self.client.post(“/login”, json={“username”:“foo”, “password”:“bar”})

小结

本文先了解了Locust的背景和生态，它是值得学习的，对于Python技术栈来说更加如此。接着介绍了使用pip命令安装Locust，其中发现顺带安装了flask，Locust的Web功能是flask提供的。

然后给出了一段示例代码，按照步骤上手Locust。最后对示例代码进行了解析，浅尝辄止。locustfile实际上该怎么写呢？

参考资料：

https://locust.io/

https://docs.locust.io/en/stable/

我们的文章到此就结束啦，如果你喜欢今天的 Python 教程，请持续关注Python实用宝典。

有任何问题，可以在公众号后台回复：加群，回答相应验证信息，进入互助群询问。

原创不易，希望你能在下面点个赞和在看支持我继续创作，谢谢！

我要打赏

Python实用宝典 ( pythondict.com )
不只是一个宝典
欢迎关注公众号：Python实用宝典

github、开发工具

Birdseye 极其强大的Python调试工具

2021年5月2日 Python实用宝典留下评论

Birdseye是一个Python调试器，它在函数调用中记录表达式的值，并让你在函数**退出**后轻松查看它们。例如：

无论你如何运行或编辑代码，都可以使用Birdseye。只需要你安装好依赖：

pip install birdseye

并在代码函数上方添加 @eye 装饰器（如上所示），即可根据需要运行函数，并在浏览器中查看结果。

它还可以与一些常用工具集成在一起，如 Pycharm 和 Vscode，以提供更流畅的体验，后续我们会介绍如何将其与这些工具结合使用。

它不仅仅能够单步执行，还能在循环迭代中来回移动，并查看所选表达式的值如何变化：

通过 birdseye 你能很容易地知道哪些表达式引发了异常：

你也能够展开具体的数据结构和对象以查看其内容:

调用会按功能组织（文件组织）并进行时间排序进行显示，让你一目了然地看到发生了什么：

1.快速上手

首先，使用 pip 安装 birdseye ：

pip install birdseye

然后，对需要进行调试的函数使用eye装饰器：

from birdseye import eye

@eye
def foo():

在你调用该函数完成后，在终端运行命令打开Birdseye的Web服务：

python -m birdseye

在浏览器打开 http://localhost:7777 就能看到需要调试的函数执行流程了。点击下图的按钮即可跳转到最新的函数调用。

2.Birdseye在Pycharm中集成调试

在 Pycharm 的 Settings 中，点击 Plugins 插件市场搜索 birdseye 点击 install 安装。

安装完成后重启Pycharm，就可以在 Pycharm 中使用 birdseye了：

默认情况下，该插件还可以为你自动运行Birdseye服务器，因此就不需要输入 python -m birdseye 那行命令了。

3.Birdseye在VSCode中集成调试

在VSCode中继承调试Birdseye也非常方便，点击左侧的扩展商店，在弹出框中输入搜索 birdseye，并点击 install 安装：

安装完成后，点击 F1 输入Birdseye，就能显示调试界面：

如果无法正常显示右侧调试界面，并提示未安装birdseye，但实际上你已经安装成功了，这一般是路径错误导致的，请在扩展设置中手动更改python路径为你安装了Birdseye的Python。

4.美中不足

Birdseye 是一个非常强大的调试工具，但我认为这还是有缺点可以改善的：

1.为了防止堆栈过大，每个迭代它最多只保留6个(前三、末三)元素：

因此如果你想看一些特殊元素值的执行情况，它可能不会如你所愿。

不过，不需要担心某些分支你调试不到，因为 birdseye 有个保险机制：如果一个表达式仅在某种特定情况下会被执行，那么执行时的元素也会被加入到可调试元素中。

2.由于需要记录堆栈，程序会大大减慢速度，因此它绝对不适合上到生产环境。

3.每个函数调用，Birdseye 都需要收集许多数据，对于某些极其复杂的函数调用，可能会引发内存问题。

如果你不担心这三个缺点，而且希望能快速方便地看到函数中不同分支的执行情况，那么Birdseye就是你的不二之选。

我们的文章到此就结束啦，如果你喜欢今天的 Python 教程，请持续关注Python实用宝典。

有任何问题，可以在公众号后台回复：加群，回答相应验证信息，进入互助群询问。

原创不易，希望你能在下面点个赞和在看支持我继续创作，谢谢！

我要打赏

Python实用宝典 ( pythondict.com )
不只是一个宝典
欢迎关注公众号：Python实用宝典

github、开发工具

Pyforest ！自动导入代码所需的 Python 库

2021年5月1日 Python实用宝典

今天给大家介绍一个懒人 Python 库：Pyforest，只用一行代码，就能导入所有的 Python 库(本地已经安装的)。

项目地址：https://github.com/8080labs/pyforest

/ 01 / 介绍

Python 因为有着成千上万个功能强大的开源库，备受大家的欢迎

目前，通过 PyPl 可以导入超过 23.5 万个 Python 库，数量庞大

在大家平常的实践当中，一般都是需要导入多个库或者框架来执行任务

而且每当新建一个程序文件时，都需要根据自己的需求导入相关的库

如果是相同类型的任务，比如想做一个数据可视化的小项目，可能会一直使用到某个库

如此，反复编写同一条 import 语句，就算是复制粘贴，也会感觉到麻烦，这时 Pyforest 库就可以上场了

Pyforest 是一个开源的 Python 库，可以自动导入代码中使用到的 Python 库

在进行数据可视化的时候，一般都需要导入多个库，比如 pandas、numpy、matplotlib 等等

使用了 Pyforest，每个程序文件中就不需要导入相同的 Python 库，而且也不必使用确切的导入语句

比如下面这行代码，就可以省略掉

from sklearn.ensemble import RandomForestClassifier

在你使用 import 语句导入Pyforest 库后，你就可以直接使用所有的 Python 库

import pyforest

df = pd.read_csv(‘test.csv’)
print(df)

你使用的任何库都不需要使用 import 语句导入，Pyforest 会为你自动导入。

只有在代码中调用库或创建库的对象后，才会导入库。如果一个库没有被使用或调用，Pyforest 将不会导入它。

/ 02 / 使用

安装，使用以下命令安装 Pyforest

pip install pyforest -i https://pypi.tuna.tsinghua.edu.cn/simple

安装成功后，使用 import 语句导入它

现在，你可以直接使用相关的 Python 库，无需编写 import 导入

先以 jupiter notebook 为例，我们没有导入 pandas、seaborn 和 matplotlib 库，但是我们可以通过导入 Pyforest 库直接使用它们

读取数据，这个是国内棉花产量排行前三的省份，新疆全国第一(数据来源：国家统计局)

那么 Pyforest 可以导入所有库吗？

目前这个包包含了大部分流行的 Python 库，比如

pandas as pd
NumPy as np
matplotlob.pyplot as plt
seaborn as sns

除了这些库之外，它还提供了一些辅助的 Python 库，如 os、tqdm、re 等

如果你想查看库列表，可以使用 dir(pyforest) 进行查看，内置的是 68 个库

import pyforest

print(len(dir(pyforest)))
for i in dir(pyforest):
print(i)

————————-
68
GradientBoostingClassifier
GradientBoostingRegressor
LazyImport
OneHotEncoder
Path
RandomForestClassifier
RandomForestRegressor
SparkContext
TSNE
TfidfVectorizer
…

如果没有的话，可以进行自定义添加，在主目录中的文件写入 import 语句

示例如下

vim ~/.pyforest/user_imports.py

添加语句，此处便能在代码中使用 requests 这个库

# Add your imports here, line by line
# e.g
# import pandas as pd
# from pathlib import Path
# import re

import requests as req
~
~
“~/.pyforest/user_imports.py” 7L, 129C

这回我们在 PyCharm 中来实验一下。

发现 PyCharm 的自动补全的功能失效了，看来这个库还是比较适合 jupyter notebook(自动补全代码还可以使用)

除了上面这个地方可以自定义添加，还可以在库的 _import.py 文件中添加

此处以 Pyechars 为例，缩写为 chart

可视化代码如下

新疆棉花产量年年上升，其它省份年年下降…

最后 Pyforest 还提供了一些函数来了解库的使用情况

# 返回已导入并且正在使用的库列表
print(pyforest.active_imports())
——————————–
[‘import pandas as pd’, ‘import requests as req’, ‘import pyg2plot’]

# 返回pyforest中所有Python库的列表
print(pyforest.lazy_imports())
——————————–
[‘import glob’, ‘import numpy as np’, ‘import matplotlib.pyplot as plt’…]

只有代码中有使用到的库，程序才会 import 进去，否则不会导入的哦！

/ 03 / 总结

好了，到此本期的分享就结束了

使用 Pyforest 库有时候确实是可以节省一些时间，不过也是有弊端存在的。比如调试的时候(大型项目)，可能会很痛苦，不知道是哪里来的库

所以建议大家，在一些独立的脚本程序中使用，效果应该还是不错的

我们的文章到此就结束啦，如果你喜欢今天的 Python 教程，请持续关注Python实用宝典。

有任何问题，可以在公众号后台回复：加群，回答相应验证信息，进入互助群询问。

原创不易，希望你能在下面点个赞和在看支持我继续创作，谢谢！

我要打赏

Python实用宝典 ( pythondict.com )
不只是一个宝典
欢迎关注公众号：Python实用宝典

规范、解决方案

Python 下划线_的五大作用—临时变量、保护变量、私有变量、魔术方法…

2021年5月1日 Python实用宝典

Python有很多地方使用下划线。在不同场合下，有不同含义：比如_var表示内部变量；__var表示私有属性；__var__表示魔术方法；这些含义有的是程序员群体的约定，如_var；有的是Python解释器规定的形式，如__var。

本文总结Python语言编程中常用下划线的地方，力图一次搞懂_用法。目前常见的用法有五种：

_用于临时变量
var_用于解决命名冲突问题
_var用于保护变量
__var用于私有变量
__var__用于魔术方法

下面我们具体看看这些下划线应用场景。

一、`_`用于临时变量

单下划线一般用于表示临时变量，在REPL、for循环和元组拆包等场景中比较常见。

1.1 REPL

单下划线在REPL中关联的是上一次计算的非None结果。

>>> 1+1
2
>>> _
2
>>> a=2+2
>>> _
2

1+1，结果为2，赋值给_；而赋值表达式a=2+2a为4，但整个表达式结果为None，故不会关联到_。这有点类似日常大家使用的计算器中的ANS按键，直接保存了上次的计算结果。

1.2 for循环中的_

for循环中_作为临时变量用。下划线来指代没什么意义的变量。例如在如下函数中，当我们只关心函数执行次数，而不关心具体次序的情况下，可以使用_作为参数。

nums = 13
for _ in range(nums):
    fun_oper()

1.3 元组拆包中的_

第三个用法是元组拆包，赋值的时候可以用_来表示略过的内容。如下代码忽略北京市人口数，只取得名字和区号。

>>> city,_,code = ('Beijing',21536000,'010')
>>> print(city,code)
Beijing 010

如果需要略过的内容多于一个的话，可以使用*开头的参数，表示忽略多个内容。如下代码忽略面积和人口数，只取得名字和区号

city,*_,code = ('Beijing',21536000,16410.54,'010')

1.4 国际化函数

在一些国际化编程中，_常用来表示翻译函数名。例如gettext包使用时：

import gettext
zh = gettext.tranlation('dict','locale',languages=['zh_CN'])
zh.install()
_('hello world')

依据设定的字典文件，其返回相应的汉字“你好世界”。

1.5 大数字表示形式

_也可用于数字的分割，这在数字比较长的时候常用。

>>> a = 9_999_999_999
>>> a
9999999999

a的值自动忽略了下划线。这样用_分割数字，有利于便捷读取比较大的数。

二、`var_`用于解决命名冲突问题

变量后面加一个下划线。主要用于解决命名冲突问题，元编程中遇时Python保留的关键字时，需要临时创建一个变量的副本时，都可以使用这种机制。

def type_obj_class(name,class_):
    pass

def tag(name,*content,class_):
    pass

以上代码中出现的class是Python的保留关键字，直接使用会报错，使用下划线后缀的方式解决了这个问题。

三、`_var`用于保护变量

前面一个下划线，后面加上变量，这是仅供内部使用的“保护变量”。比如函数、方法或者属性。

这种保护不是强制规定，而是一种程序员的约定，解释器不做访问控制。一般来讲这些属性都作为实现细节而不需要调用者关心，随时都可能改变，我们编程时虽然能访问，但是不建议访问。

这种属性，只有在导入时，才能发挥保护作用。而且必须是from XXX import *这种导入形式才能发挥保护作用。

使用from XXX import *是一种通配导入（wildcard import），这是Python社区不推荐的方式，因为你根本搞不清你到底导入了什么属性、方法，很可能搞乱你自己的命名空间。PEP8推荐的导入方式是from XXX import aVar , b_func , c_func这种形式。

比如在下例汽车库函数tools.py里定义的“保护属性”：发动机型号和轮胎型号，这属于实现细节，没必要暴露给用户。当我们使用from tools import * 语句调用时，其实际并没有导入所有_开头的属性，只导入了普通drive方法。

_moto_type = 'L15b2'
_wheel_type = 'michelin'

def drive():
    _start_engine()
    _drive_wheel()

def _start_engine():
    print('start engine %s'%_moto_type)
    
def _drive_wheel():
    print('drive wheel %s'%_wheel_type)

查看命令空间print(vars())可见，只有drive函数被导入进来，其他下划线开头的“私有属性”都没有导入进来。

{'__name__': '__main__', '__doc__': None, '__package__': None, '__loader__': <_frozen_importlib_external.SourceFileLoader object at 0x005CF868>, '__spec__': None, '__annotations__':{}, '__builtins__': <module 'builtins' (built-in)>, '__file__': '.\\xiahuaxian.py', '__cached__': None, 'walk': <function walk at 0x01DA8C40>, 'root': '.\\__pycache__', '_': [21536000, 16410.54], 'dirs': ['tools.cpython-38.pyc'], 'city': 'Beijing', 'code': '010', 'drive': <function drive at 0x01DBC4A8>}

3.1 突破保护属性

之所以说是“保护”并不是“私有”，是因为Python没有提供解释器机制来控制访问权限。我们依然可以访问这些属性：

import tools
tools._moto_type = 'EA211'
tools.drive()

以上代码，以越过“保护属性”。此外，还有两种方法能突破这个限制，一种是将“私有属性”添加到tool.py文件的__all__列表里，使from tools import *也导入这些本该隐藏的属性。

__all__ = ['drive','_moto_type','_wheel_type']

另一种是导入时指定“受保护属性”名。

from tools import drive,_start_engine
_start_engine()

甚至是，使用import tools也可以轻易突破保护限制。所以可见，“保护属性”是一种简单的隐藏机制，只有在from tools import *时，由解释器提供简单的保护，但是可以轻易突破。这种保护更多地依赖程序员的共识：不访问、修改“保护属性”。除此之外，有没有更安全的保护机制呢？有，就是下一部分讨论的私有变量。

四、`__var`用于私有变量

私有属性解决的之前的保护属性保护力度不够的问题。变量前面加上两个下划线，类里面作为属性名和方法都可以。两个下划线属性由Python的改写机制来实现对这个属性的保护。

看下面汽车例子中，品牌为普通属性，发动机为“保护属性”，车轮品牌为“私有属性”。

class Car:
    def __init__(self):
        self.brand = 'Honda'
        self._moto_type = 'L15B2'
        self.__wheel_type = 'michelin'

    def drive(self):
        print('Start the engine %s,drive the wheel %s,I get a running %s car'%
        (self._moto_type,
        self.__wheel_type,
        self.brand))

我们用var(car1)查看下具体属性值，

['_Car__wheel_type', '__class__', '__delattr__', '__dict__', '__dir__', '__doc__', '__eq__', '__format__', '__ge__', '__getattribute__', '__gt__', '__hash__', '__init__', '__init_subclass__', '__le__', '__lt__', '__module__', '__ne__', '__new__', '__reduce__', '__reduce_ex__', '__repr__', '__setattr__', '__sizeof__', '__str__', '__subclasshook__', '__weakref__', '_moto_type', 'brand', 'drive']

可见，实例化car1中，普通属性self.brand和保护属性self._moto_type都得以保存，两个下划线的私有属性__wheel_type没有了。取而代之的是_Car_wheel_type这个属性。这就是改写机制（Name mangling）。两个下划线的属性，被改写成带有类名前缀的变量，这样子类很难明明一个和如此复杂名字重名的属性。保证了属性不被重载，保证了其的私有性。

4.1 突破私有属性

这里“私有变量”的实现，是从解释器层面给与的改写，保护了私有变量。但是这个机制并非绝对安全，因为我们依然可以通过obj._ClasssName__private来访问__private私有属性。

car1.brand = 'Toyota'
car1._moto_type = '6AR-FSE'
car1._Car__wheel_type = 'BRIDGESTONE'
car1.drive()

结果

Start the engine 6AR-FSE,\
drive the wheel BRIDGESTONE,\
I get a running Toyota car

可见，对改写机制改写的私有变量，虽然保护性加强了，但依然可以访问并修改。只是这种修改，只是一种杂耍般的操作，并不可取。

五、`var`用于魔术方法

变量前面两个下划线，后面两个下划线。这是Python当中的魔术方法，一般是给系统程序调用的。例如上例中的__init__就是类的初始化魔术方法，还有支持len函数的__len__方法，支持上下文管理器协议的__enter__和__exit__方法，支持迭代器协议的__iter__方法，支持格式化显示的__repr__和__str__方法等等。这里我们为上例的Car类添加魔术方法__repr__来支持格式化显示。

    def __repr__(self):
        return '***Car %s:with %s Engine,%sWheel***'%
        (self.brand,self._moto_type,self.__wheel_type)

未添加__repr__魔术方法之前，print(car1)结果为<__main__.Car object at 0x0047F7F0>，这个结果让人看的一头雾水，增加repr魔术方法之后，显示结果为***Car Toyota:with 6AR-FSE Engine,BRIDGESTONE Wheel***清晰明了，利于调试。这就是魔术方法的功效：支持系统调用，改进用户类表现，增加协议支持，使用户类表现得更像系统类。

5.1 Python魔术方法分类

以下所有魔术方法均需要在前后加上__，这里省略了这些双下划线。

一元运算符 neg pos abs invert
转换 complex int float round inex
算术运算 add sub mul truediv floordiv mod divmod pow lshift rshift and xor or

算术运算除and之外，前面再加上r，表示反运算。除dimod外，前面加上i，表示就地运算。

比较 lt le eq ne gt ge
类属性 getattr getattribute setattr delattr dir get set delete
格式化 bytes hash bool format
类相关 init del new
列表 getitem
迭代器 iter next
上下文管理器 enter exit

六、总结

总之，下划线在 Python 当中应用还是很广泛的，甚至可以说 Python 对下划线有所偏爱

可以看到 _常用于临时变量，在REPL，for循环，元组拆包和国际化中得到了广泛应用

var_用于解决命名冲突问题，使用时比较简单易懂的。_var对变量的保护，只是一种脆弱的保护，更多依靠程序员的约定。__var用于私有变量，借助改写机制支持，已经支持了私有变量，但是仍然存在漏洞

对__var__用于魔术方法，进行了一个简单的介绍，魔术方法较多，但是理解并不复杂。希望以后可以进一步介绍这些魔术方法

继续阅读Python 下划线_的五大作用—临时变量、保护变量、私有变量、魔术方法… →

github、Python 办公

整理的关于 pip 的 15 个使用小技巧

2021年5月1日 Python实用宝典

本文转载自公众号【 Python大数据分析】

认识pip

众所周知，pip可以对python的第三方库进行安装、更新、卸载等操作，十分方便。

pip的全称：package installer for python，也就是Python包管理工具。

可能有些人用了很久pip，但还不清楚包管理工具是个啥。

我们先从Python这门语言说起，Python之所以受欢迎不光是因为它简单易学，更重要的是它有成千上万的宝藏库。

这些库相当于是已经集成好的工具，只要安装就能在Python里使用。它们可以处理各式各样的问题，无需你再造轮子，而且随着社区的不断更新维护，有些库越来越强大，几乎能媲美企业级应用。

那么这些工具库怎么下载安装呢？它们被放在一个统一的“仓库”里，名叫PyPi（Python Package Index），所有的库安装都是从这里调度。

有了仓库之后，还需要有管理员，pip就是这样一个角色。pip把库从PyPi取出来，然后安装到Python里，还可以管理安装好的库，比如更新、查看、搜索、卸载等等。

总的来说，pip的Python第三方库的大管家，搞懂它，会让你省很多事。

下面总结了30个pip使用过程中的常识和技巧，供大家参考。

「注：因为pip是一个命令行程序，所以pip一般都在命令行中执行各种操作」

1、安装pip

从Python 3.4开始，pip已经内置在Python中，所以无需再次安装。

如果你的Python版本没有pip，那可以使用下面两种方法安装。

(1) 命令行中输入easy_install pip，非常快捷

(2) 在下面网址中下载pip安装文件，然后解压到python scripts目录中，执行python setup.py install安装即可

下载网址：https://pypi.org/project/pip/#files

下载文件：

2、查看pip版本

pip --version

3、升级pip

如果pip的版本太低，可以升级当前版本
pip install --upgrade pip

4、获取帮助

想了解如何使用pip，以及pip有哪些功能，执行下面语句可以获取详细教程:
pip help

5、安装库

使用pip安装第三方库，执行下面语句
pip install package_name

指定package版本：
pip install package_name==1.1.2

比如说，我要安装3.4.1版本的matplotlib
pip install matplotlib==3.4.1

6、批量安装库

如果一个项目需要安装很多库，那可以批量安装：
pip install -r e:\\requirements.txt

requirements.txt文件内容格式如下：

7、使用wheel文件安装库

这种方法适合离线安装，wheel文件是库的源文件，可以下载后放到本地安装。

步骤如下：

(1) 在下面网站里找相应库的.whl文件
https://www.lfd.uci.edu/~gohlke/pythonlibs/

(2) 下载.whl文件，注意对应的版本

(3) 在.whl所在文件夹内，按Shift键+鼠标右键，打开CMD窗口或者PowerShell

(4) 输入命令：
pip install matplotlib‑3.4.1‑cp39‑cp39‑win_amd64.whl
即可完成安装

8、卸载库

安装好的库可以再卸载：
pip uninstall package_name

9、升级库

对当前库进行版本升级:
pip install --upgrade package_name

10、查看库信息

pip show -f package_name

11、查看已安装的库

列出所有已安装的第三方库和对应版本
pip list

12、将库列表保存到指定文件中

把已经安装的库信息保存到到本地txt文件中：
pip freeze > requirements.txt

13、查看需要升级的库

目前已经安装的库中，看哪些需要版本升级
pip list -o

14、检查兼容问题

验证已安装的库是否有兼容依赖问题
pip check package-name

15、下载库到本地

将库下载到本地指定文件，保存为whl格式
pip download package_name -d "要保存的文件路径"

附：更换pip源

很多人抱怨pip安装库有些时候太慢了，那是pip源的问题。

前面说过pip从PyPi中下载库文件，但由于PyPi服务器在国外，访问起来很慢。

但国内提供了很多镜像源，用来替代PyPi，像清华源、豆瓣源、阿里云源等。

这些镜像源备份了PyPi里的数据，由于服务器在国内，速度会快很多。

但镜像源数据有滞后性，比如说清华源的pypi 镜像每 5 分钟同步一次。

使用镜像源有两种方式，以清华源为例：

(1) 临时使用

pip install -i https://pypi.tuna.tsinghua.edu.cn/simple some-package matplotlib

除了matplotlib是要安装的库名外，其他都是固定格式

(2) 设为默认

pip config set global.index-url https://pypi.tuna.tsinghua.edu.cn/simple

设为默认后，以后安装库都是从清华源下载，而且无需再加镜像源网址

附主流镜像源地址

清华：https://pypi.tuna.tsinghua.edu.cn/simple
阿里云：http://mirrors.aliyun.com/pypi/simple/
中国科技大学 https://pypi.mirrors.ustc.edu.cn/simple/
华中理工大学：http://pypi.hustunique.com/
山东理工大学：http://pypi.sdutlinux.org/
豆瓣：http://pypi.douban.com/simple/

我们的文章到此就结束啦，如果你喜欢今天的 Python 教程，请持续关注Python实用宝典。

有任何问题，可以在公众号后台回复：加群，回答相应验证信息，进入互助群询问。

原创不易，希望你能在下面点个赞和在看支持我继续创作，谢谢！

我要打赏

Python实用宝典 ( pythondict.com )
不只是一个宝典
欢迎关注公众号：Python实用宝典

解决方案

超详细快速部署 Python 脚本到手机上

2021年5月1日 Python实用宝典

1. 前言

最近有读者后台给我留言，说这段时间云服务器涨价了，自己日常就运行一些简单的脚本，因此不太想入坑云服务器，问我能不能提供一个不一样的思路给他

本篇文章将介绍一款软件，即：iSH

这款 App 功能非常强大，可以运行各种脚本，适用于需求不是很大的小伙伴

2. 介绍

iSH 是一款运行在 iOS 系统上的 App，可以运行 Linux Shell，底层操作系统基于「 Alpine 」

PS：Alpine 是一个超轻量级的 Linux 发行版，是一个由社区开发的 Linux 操作系统，该操作系统以安全为理念，面向 x86 路由器、防火墙、虚拟专用网、IP 电话盒及服务器而设计

项目地址：

https://github.com/ish-app/ish/

安装有 2 种方式，分别是：

App Store 搜索关键字「 iSH 」下载
Github 下载源码，使用 Xcode 编译安装

App 界面如下，从左往右，功能键包含：Tab 键、Ctrl 键、ESC 键、滚动键（ Arrow 键）、软件设置、快速粘贴键、隐藏输入法

其中，

Tab 键、Ctrl 键、ESC 键和 PC 端使用方法一致

滚动键用于光标移动和历史命令切换（通过向上、向下滑动来切换历史命令）

设置中，可以对外观主题、文字样式、应用图标、文件管理进行查看设置

3. 更换源及安装依赖

由于默认的源在国外，下载依赖很慢，我们需要更换源

使用 vim 命令编辑文件「 /etc/apk/repositories 」，删除默认的源，更换为阿里或者清华的源

# 编辑文件
vim /etc/apk/repositories

# 替换为国内的源
# 阿里源
https://mirrors.aliyun.com/alpine/v3.11/main
https://mirrors.aliyun.com/alpine/v3.11/community

编辑完成后，保存退出

下面就可以安装 Python 及常见依赖库了

3-1 安装 Python3

iSH 使用命令「 apk add app_name 」安装应用程序

# 安装python3
apk add python3

3-2 安装 pip

首先，我们使用「 wget 」命令下载 pip 文件，然后安装 pip

# 下载get-pip文件
wget https://bootstrap.pypa.io/get-pip.py

# 安装
python3 get-pip.pya

3-3 安装依赖包

以最常见的 requests 为例，直接使用 pip3 安装即可

# 安装依赖
pip3 install requests

需要注意的是，iSH 安装速度比较慢，需要耐心等待

4. 执行脚本

由于手机上编辑脚本效率太低，大部分时候我们都是在 PC 端编写完成，然后导入到 iSH 中运行

常见方案为 iSH + SSH + Git，为了演示方便，我这里使用「 Web Server for Chrome 」在 PC 端搭建了文件共享服务器，然后将脚本文件放置到共享目录

然后再 iSH 终端，使用 wget 命令直接下载脚本文件

最后，进入到脚本文件夹目录，运行脚本文件即可

# 下载脚本文件压缩包
wget http://192.168.2.121:8887/rsc.zip

# 解压文件
unzip rsc.zip

# 进入到文件夹目录
cd rsc/

# 运行脚本文件
python3 main_proj.py

5. 拓展一下

iSH 常见命令如下：

5-1 安装

apk add <name>
apk add vim
apk add python3

5-2 卸载

# 卸载应用
apk del <name>

5-3 搜索应用

# 搜索应用
# PS：可以先搜索，然后再安装
apk search <name>

5-4 更新包管理器

iSH 使用 Alpine 包管理器，使用下面的命令可以更新 Alpine 存储库列表

# 更新存储库列表
apk update

6. 总结

iSH 作为一款 iOS 端的应用，可以非常便捷地完成 Python 脚本的部署运行，当然 Shell 脚本也是支持的

另外，iSH 可以开启 SSH Server 供远程连接，这部分内容及 iSH 详细使用文档我已经写成 PDF 并上传到后台，回复关键字「 iSH 」获取完整内容

我们的文章到此就结束啦，如果你喜欢今天的 Python 教程，请持续关注Python实用宝典。

有任何问题，可以在公众号后台回复：加群，回答相应验证信息，进入互助群询问。

原创不易，希望你能在下面点个赞和在看支持我继续创作，谢谢！

我要打赏

Python实用宝典 ( pythondict.com )
不只是一个宝典
欢迎关注公众号：Python实用宝典

规范

Google 内部的 Python 代码风格指南

2021年5月1日 Python实用宝典

来自：Why GitHub?

https://github.com/shendeguize/GooglePythonStyleGuideCN

这是一位朋友翻译的 Google Python代码风格指南，很全面。可以作为公司的 code review 标准，也可以作为自己编写代码的风格指南，希望对你有帮助

Translator: shendeguize@github

Link: https://github.com/shendeguize/GooglePythonStyleGuideCN

本翻译囿于水平，可能有不准确的地方，欢迎指出，谢谢大家

1、背景

Python 是谷歌主要使用的动态语言，本风格指导列举了使用 Python 编程时应该做和不该做的事项( dos & don’ts )

为了帮助你正确地组织代码，我们编写了一个 Vim 的设置文件.对于 Emacs，默认设置即可.

许多团队使用 yapf 自动格式工具来避免格式争议

2、Python语言规则

2.1 Lint

对代码使用pylint

2.1.1Definition(以下都译为定义)

pylint是一个用于在Python代码中发现bug和代码风格问题的工具,，pylint查找那些常在非动态语言(例如C或C++)编译器中捕获的问题.由于Python是动态语言,一些警告可能不正确,不过应该非常少有错误警告.

2.1.2 Pros

能够发现一些易被遗漏的错误,类似拼写错误,调用早于声明等等.

2.1.3 Cons

pylint并不完美,为了更好的利用工具,我们有时候需要

a. Write around it(适配上下文风格)

b. 压制一些警告

c. 优化工具

2.1.4 Decision(以下都译为建议)

确保对代码应用pylint

如果一些警告是不合适的,就抑制这些警告,这是为了让其他警告不会被隐藏.为了压制警告,可以设置行级别的注释:

dict = 'something awful'  # Bad Idea... pylint: disable=redefined-builtin

pylint警告包含标识名(empty-docstring),谷歌专有的警告以g-开头.

如果抑制警告的原因在标识名称中表述不够清晰,请额外添加注解.

用这种方式来抑制警告的优点是我们能够简单地找到抑制的警告并且重新访问这些警告.

可以通过下述方式来获得pylint警告列表:

pylint --list-msgs

用下述方式来获取某个特定消息的更多具体信息:

pylint --help-msg=C6409

优先使用pylint: disable而非旧方法(pylint: disable-msg)如果要抑制由于参数未使用的警告,可以在函数开头del,并注释为什么要删除这些未使用参数,仅仅一句”unused”是不够的:

def viking_cafe_order(spam, beans, eggs=None):
    del beans, eggs  # Unused by vikings.
    return spam + spam + spa

其他可以用来抑制警告的方式包括用'_'作为未使用参数的标识,在参数名前增加'unused_',或者分配这些参数到'_'.这些方式是可以的,但是已经不鼓励继续使用.前两种方式会影响到通过参数名传参的调用方式,而最后一种并不能保证参数确实未被使用.

2.2 Imports

只在import包和模块的时候使用import,而不要应用在单独的类或函数.(这一条对于typing_module有特别的意外)

2.2.1 定义

一个模块到另一个模块之间共享代码的复用性机制

2.2.2 Pros

命名空间管理约定简单,每个标识的源都一致性地被指明了.例如x.Obj表示Obj是在模块x中定义的

2.2.3 Cons

模块名可能会有冲突,一些模块名可能很长,比较不方便

2.2.4 建议

import x（当x是包或模块）
from x import y （当x是包前缀，y是不带前缀的模块名）
from x import y as z （当有重复模块名y或y过长不利于引用的时候）
import y as z （仅在非常通用的简写的时候使用例如import numpy as np）

以sound.effects.echo为例:

from sound.effects import echo...echo.EchoFilter(input, output, delay=0.7, atten=4)

不要使用相对引用，即便在同一包内，也使用完整包名import,这有助于避免无意重复import包.

从typing module和six.moves module import不适用上述规则

2.3 包

每一模块都要从完整路径import

2.3.1 Pros

能够避免模块名冲突以及由于模块搜索路径与作者预期不符而造成的错误引用.让查找模块更简单.

2.3.2 Cons

让部署代码时有些困难,因为包架构也需要赋值,不过对于现在的部署机制而言,这其实不是问题.

2.3.3 建议

所有的新代码都要从完整包名来import模块

import示例应该像这样:

Yes:

# Reference absl.flags in code with the complete name (verbose).
# 在代码中使用完整路径调用absl.flags
import absl.flagsfrom doctor.who import jodie

FLAGS = absl.flags.FLAGS

# Reference flags in code with just the module name (common).
# 在代码中只用包名来调用flags
from absl import flagsfrom doctor.who import jodie

FLAGS = flags.FLAGS

No:(假设文件在doctor/who中,jodie.py也在这里)

# Unclear what module the author wanted and what will be imported.  The actual
# import behavior depends on external factors controlling sys.path.
# Which possible jodie module did the author intend to import?
# 不清楚作者想要哪个包以及最终import的是哪个包,
# 实际的import操作依赖于受到外部参数控制的sys.path
# 那么哪一个可能的jodie模块是作者希望import的呢?
import jodie

不应该假设主代码所在路径被包含在sys.path中,即使有些时候可以work.在上一例代码中,我们应该认为import jodie指的是import一个叫做jodie的第三方包或者顶级目录中的jodie,而非一个当前路径的jodie.py

2.4 异常

异常处理是允许使用的,但使用务必谨慎

2.4.1 定义

异常是一种从正常代码段控制流中跳出以处理错误或者其他异常条件的手段.

2.4.2 Pros

正常代码的控制流时不会被错误处理代码影响的.异常处理同样允许在某些情况下,控制流跳过多段代码,例如在某一步从N个嵌入函数返回结果而非强行延续错误代码.

2.4.3 Cons

可能会让控制流变的难于理解,也比较容易错过调用库函数的报错.

2.4.4 建议

异常必定遵循特定条件:

使用raise MyError('Error message')或者raise MyError()，不要使用两段raise MyError, 'Error message'
当内置异常类合理的时候,尽量使用内置异常.例如:抛出ValueError来表示一个像是违反预设前提(例如传参了一个负数给要求正数的情况)的程序错误发生.

不要使用assert来片段公共结构参数值.assert是用来确认内部计算正确性也不是用来表示一些预期外的事件发生的.如果异常是后续处理要求的,用raise语句来处理,例如:

Yes:

def connect_to_next_port(self, minimum):
"""Connects to the next available port.

Args:
    minimum: A port value greater or equal to 1024.

Returns:
    The new minimum port.

Raises:
    ConnectionError: If no available port is found.
"""
if minimum < 1024:
    # Note that this raising of ValueError is not mentioned in the doc
    # string's "Raises:" section because it is not appropriate to
    # guarantee this specific behavioral reaction to API misuse.
    # 注意抛出ValueError这件事是不在docstring中的Raises中提及, 因为这样并适合保障对于API误用的特殊反馈
    raise ValueError('Minimum port must be at least 1024, not %d.' % (minimum,))
port = self._find_next_open_port(minimum)
if not port:
    raise ConnectionError('Could not connect to service on %d or higher.' % (minimum,))
assert port >= minimum, 'Unexpected port %d when minimum was %d.' % (port, minimum)
return port

No:

def connect_to_next_port(self, minimum):
"""Connects to the next available port.

Args:
    minimum: A port value greater or equal to 1024.

Returns:
    The new minimum port.
"""
assert minimum >= 1024, 'Minimum port must be at least 1024.'
port = self._find_next_open_port(minimum)
assert port is not None
return port

库或者包可能会定义各自的异常.当这样做的时候,必须要继承一个已经存在的异常类,异常类的名字应该以Error结尾,并且不应该引入重复(foo.FooError)
永远不要用捕获全部异常的except:语句,或者捕获Exception或者StandardError除非:

Python在这个方面容忍度很高,并且except:语句会捕获包括拼写错误,sys.exit(),Ctrl+C终止,单元测试失败和和所有你并没有想到捕获的其他异常.
- 再次抛出这个异常
- 在程序中异常不会继续但是会被记录以及消除(例如通过保护最外层的方式保护线程不会崩溃)的地方创造一个孤立点.
最精简try/except表达式内部的代码量,try代码块里的代码体量越大,月可能会在你不希望抛出异常的代码中抛出异常,进而在这种情况下,try/except掩盖了一个真实的异常
使用finally来执行代码,这些代码无论是否有异常在try代码块被抛出都会被执行.这在清理(即关闭文件)时非常有用.
当捕获了异常时,用as而不是逗号分段.

try:
    raise Error()
except Error as error:
    pass

2.5 全局变量

避免全局变量

2.5.1 定义

在模块级别或者作为类属性声明的变量

2.5.2 Pros

有些时候有用

2.5.3 Cons

在import的过程中,有可能改变模块行为,因为在模块首次被引入的过程中,全局变量就已经被声明

2.5.4 建议

避免全局变量

作为技术变量,模块级别的常量是允许并鼓励使用的.例如MAX_HOLY_HANDGRENADE_COUNT = 3, 常量必须由大写字母和下划线组成,参见下方命名规则

如果需要,全局变量需要在模块级别声明,并且通过在变量名前加_来使其对模块内私有化.外部对模块全局变量的访问必须通过公共模块级别函数,参见下方命名规则

2.6 内嵌/局部/内部类和函数

内嵌局部函数或类在关闭局部变量时是可以的.内部类意识可用的.(译注:这里我的理解是当内嵌局部函数或类是和局部变量在同一个封闭作用域内是可以的.)

2.6.1 定义

类可以在方法,函数,类内定义.函数可以在方法或函数内定义.内嵌函数对封闭作用域的变量具有只读访问权限.

2.6.2 Pros

允许定义只在非常有限作用域内可用的工具类或工具函数.Very ADT-y(??符合抽象数据类型要求???),通常用于实现装饰器

2.6.3 Cons

内嵌或局部类的实例是不能被pickle的,内嵌函数或类是不能被直接测试的.嵌套会让外部函数更长并且更难读懂.

2.6.4 建议

除了一些特别声明,这些内嵌/局部/内部类和函数都是可以的.避免内嵌函数或类除了需要关闭一个局部值的时候.(译者理解可能是除了将局部变量封闭在同一个作用域的情况以外).不要把一个函数转为内嵌指示为了避免访问.在这种情况下,把函数置于模块级别并在函数名前加_以保证测试是可以访问该函数的.

2.7 列表推导和生成器表达式

在简单情况下是可用的

2.7.1 定义

List, Dict和Set推导生成式以及生成器表达式提供了一个简明有效的方式来生成容器和迭代器而不需要传统的循环,map(),filter()或者lambda表达式

2.7.2 Pros

简单地推导表达比其他的字典,列表或集合生成方法更加简明清晰.生成器表达式可以很有效率,因为完全避免了生成列表.

2.7.3 Cons

负载的推导表达式或生成器表达式很难读懂

2.7.4 建议

简单情况下使用时可以的.每个部分(mapping表达式,filter表达式等)都应该在一行内完成.多个for条款或者filter表达式是不允许的.当情况变得很复杂的适合就使用循环.

Yes:

result = [mapping_expr for value in iterable if filter_expr]

result = [{'key': value} for value in iterable
          if a_long_filter_expression(value)]

result = [complicated_transform(x)
          for x in iterable if predicate(x)]

descriptive_name = [
    transform({'key': key, 'value': value}, color='black')
    for key, value in generate_iterable(some_input)
    if complicated_condition_is_met(key, value)
]

result = []
for x in range(10):
    for y in range(5):
        if x * y > 10:
            result.append((x, y))

return {x: complicated_transform(x)
        for x in long_generator_function(parameter)
        if x is not None}

squares_generator = (x**2 for x in range(10))

unique_names = {user.name for user in users if user is not None}

eat(jelly_bean for jelly_bean in jelly_beans
    if jelly_bean.color == 'black')

No:

result = [complicated_transform(
          x, some_argument=x+1)
          for x in iterable if predicate(x)]

result = [(x, y) for x in range(10) for y in range(5) if x * y > 10]

return ((x, y, z)
        for x in range(5)
        for y in range(5)
        if x != y
        for z in range(5)
        if y != z)

2.8 默认迭代器和运算符

对支持默认迭代器和云算法的类型例如列表,字典和文件等使用它们

2.8.1 定义

容器类型(例如字典,列表等)定义了的默认的迭代器和成员检查运算符.

Pros

默认迭代器和操作符是简单有效的,能够直接不需额外调用方法地表达操作.使用默认操作符的函数是通用的.能被用于任何支持这些操作的类型.

Cons

不能通过方法名来分辨类型,例如has_key()意味着字典,当然这也是一种优势.

建议

对于支持的类型诸如列表,字典和文件,使用默认迭代器和操作符.内置类型同样定义了迭代器方法.优先使用这些方法而非那些返回列表的方法.除非能够确定在遍历容器的过程中不会改变容器.不要使用Python 2专有迭代方法除非必要.

Yes:

for key in adict: ...
if key not in adict: ...
if obj in alist: ...
for line in afile: ...
for k, v in adict.items(): ...
for k, v in six.iteritems(adict): ...

No:

for key in adict.keys(): ...
if not adict.has_key(key): ...
for line in afile.readlines(): ...
for k, v in dict.iteritems(): ...

2.9 生成器

需要时使用生成器

2.9.1 定义

生成器函数返回一个迭代器,每次执行yield语句的时候生成一个值.在生成一个值之后,生成器函数的运行被挂起直到需要下一个值.

2.9.2 Pros

简化代码,因为局部变量和控制流在每次调用时被保留,生成器相比于一次性生成整个一个列表值要更节省内存.

2.9.3 Cons

无

2.9.4 建议

建议使用.在生成器函数的文档字符串中使用”Yields:”而非”Returns:”

2.10 Lambda表达式

单行代码时是可以的

2.10.1 定义

lambda在一个表达式内定义了匿名函数,而不在语句里.lambda表达式常被用于定义高阶函数(例如map()和filter())使用的回调函数或者操作符.

2.10.2 Pros

方便

2.10.3 Cons

比局部函数更难读懂和debug,匿名意味着堆栈跟踪更难懂.表达性受限因为lambda函数只包含一个表达式

2.10.4 建议

对于单行代码而言,可以使用lambda表达式.如果lambda表达式内的代码超过60-80个字符,最好定义成为常规的内嵌函数.

对于一般的操作诸如乘法,使用operator模块内置函数而非重新定义匿名函数,例如使用operator.mul而非lambda x,y: x * y

2.11 条件表达式

简单情况下可以使用.

2.11.1 定义

条件表达式(也称为三元运算符)是一种更短替代if语句的机制.例如x = 1 if cond else 2

2.11.2 Pros

相对于if语句更短也更方便

2.11.3 Cons

比if语句可能更难读懂,当表达式很长的时候条件部分可能很难定位.

2.11.4 建议

简单情况可以使用.每个部分(真值表达式,if表达式,else表达式)必须在一行内完成.如果使用条件表达式很富的时候使用完整的if语句.

Yes:

one_line = 'yes' if predicate(value) else 'no'
slightly_split = ('yes' if predicate(value)
                  else 'no, nein, nyet')
the_longest_ternary_style_that_can_be_done = (
    'yes, true, affirmative, confirmed, correct'
    if predicate(value)
    else 'no, false, negative, nay')

No:

bad_line_breaking = ('yes' if predicate(value) else
                     'no')portion_too_long = ('yes'
                    if some_long_module.some_long_predicate_function(
                        really_long_variable_name)
                    else 'no, false, negative, nay')

2.12 默认参数值

大多数情况下都OK

2.12.1 定义

在函数参数列表的最后可以为变量设定值,例如def foo(a, b=0):.如果foo在调用时只传入一个参数,那么b变量就被设定为0,如果调用时传入两个参数,那么b就被赋予第二个参数值.

2.12.2 Pros

通常一个函数可能会有大量默认值,但是很少会有需要修改这些默认值的时候.默认值就提供了一个很简单满足上述情况的方式,而不需要为这些少见的情况重新定义很多函数.因为Python不支持重载方法或函数,默认参数是一个很简单的方式来”假重载”行为.

2.12.3 Cons

默认参数在模块加载时就被复制.这在参数是可变对象(例如列表或字典)时引发问题.如果函数修改了这些可变对象(例如向列表尾添加元素).默认值就被改变了.

2.12.4 建议

使用时请注意以下警告—-在函数或方法定义时不要将可变对象作为默认值.

Yes:

def foo(a, b=None):
    if b is None:
        b = []
def foo(a, b: Optional[Sequence] = None):
    if b is None:
        b = []
def foo(a, b: Sequence = ()):  # Empty tuple OK since tuples are immutable 空元组是也不可变的
    ...

No:

def foo(a, b=[]):
    ...
def foo(a, b=time.time()):  # The time the module was loaded??? 模块被加载的时间???
    ...
def foo(a, b=FLAGS.my_thing):  # sys.argv has not yet been parsed... sys.argv还未被解析
    ...
def foo(a, b: Mapping = {}):  # Could still get passed to unchecked code 仍可传入未检查的代码(此处翻译可能有误)
    ...

2.13 属性

使用属性可以通过简单而轻量级的访问器和设定器方法来访问或设定数据.

2.13.1 定义

一种装饰器调用来在计算比较轻量级时作为标准的属性访问来获取和设定一个属性的方式

2.13.2 Pros

对于简单的属性访问,减少显式的get和set方法能够提升可读性.允许惰性计算.被认为是一种Python化的方式来维护类接口.在表现上,当直接对变量的访问更合理时,允许属性绕过所需的琐碎的访问方法.

2.13.3 Cons

在Python2中必须继承于object,可能会隐藏像是操作符重载之类的副作用.对于子类而言,属性可能有些迷惑性.

2.13.4 建议

在通常会有简单而且轻量级的访问和设定方法的新代码里使用属性来访问或设定数据.属性在创建时被@property装饰,参加装饰器

如果属性本身未被重写,带有属性的继承可能不够明晰,因而必须确保访问方法是被间接访问的,来确保子类的方法重载是被属性调用的(使用Template Method DP,译者:应是模板方法设计模式).

Yes:

class Square(object):
    """A square with two properties: a writable area and a read-only perimeter.

    To use:
    >>> sq = Square(3)
    >>> sq.area
    9
    >>> sq.perimeter
    12
    >>> sq.area = 16
    >>> sq.side
    4
    >>> sq.perimeter
    16
    """

    def __init__(self, side):
        self.side = side

    @property
    def area(self):
        """Area of the square."""
        return self._get_area()

    @area.setter
    def area(self, area):
        return self._set_area(area)

    def _get_area(self):
        """Indirect accessor to calculate the 'area' property."""
        return self.side ** 2

    def _set_area(self, area):
        """Indirect setter to set the 'area' property."""
        self.side = math.sqrt(area)

    @property
    def perimeter(self):
        return self.side * 4

2.14 True/False表达式

只要可能,就使用隐式False的if语句

2.14.1 定义

在布尔环境下,Python对某些值判定为False,一个快速的经验规律是所有”空”值都被认为是False,所以0, None, [], {}, ''的布尔值都是False

2.14.2 Pros

使用Python布尔类型的条件语句可读性更好而且更难出错,大多数情况下,这种方式也更快.

2.14.3 Cons

对于C/C++开发者而言可能有些奇怪

建议

如果可能的话,使用隐式False.例如使用if foo:而非if foo != []:下面列举了一些你应该牢记的警告:

使用if foo is None(或者if foo is not None)来检查None.例如在检查一个默认值是None的变量或者参数是否被赋予了其他值的时候,被赋予的其他值的布尔值可能为False.
不要用==来和布尔值为False的变量比较,使用if not x,如果需要区别False和None,那么使用链式的表达式如if not x and x is not None
对于序列(如字符串,列表,元组),利用空序列为False的事实,故而相应地使用if seq:和if not seq:而非if len(seq)或if not len(seq):.
在处理整数时,隐式的False可能会引入更多风险(例如意外地将None和0进行了相同的处理)你可以用一个已知是整形(并且不是len()的结果)的值和整数0比较.

Yes:

if not users:
    print('no users')

if foo == 0:
    self.handle_zero()

if i % 10 == 0:
    self.handle_multiple_of_ten()

def f(x=None):
    if x is None:
        x = []

No:

if len(users) == 0:
    print('no users')

if foo is not None and not foo:
    self.handle_zero()

if not i % 10:
    self.handle_multiple_of_ten()

def f(x=None):
    x = x or []

2.15 弃用的语言特性

尽可能利用字符串方法而非string模块.使用函数调用语法而非apply.在函数参数本就是一个行内匿名函数的时候,使用列表推导表达式和for循环而非filter和map

2.15.1 定义

当前Python版本提供了人们普遍更倾向的构建方式.

2.15.2 建议

我们不使用任何不支持这些特性的Python版本,因而没有理由不使用新方式.

Yes:

words = foo.split(':')

[x[1] for x in my_list if x[2] == 5]

map(math.sqrt, data)    # Ok. No inlined lambda expression. 可以,没有行内的lambda表达式

fn(*args, **kwargs)

No:

words = string.split(foo, ':')

map(lambda x: x[1], filter(lambda x: x[2] == 5, my_list))

apply(fn, args, kwargs)

2.16 词法作用域

可以使用

2.16.1 定义

一个内嵌Python函数可以引用在闭包命名空间内定义的变量,但是不能对其复制.变量绑定是解析到使用词法作用域的,即基于静态程序文本.任何对块内命名的赋值都会让Python将对于这个命名的引用都作为局部变量,即使在使用先于赋值的情况下也是.如果有全局声明,这个命名就会被认为是全局变量.

一个使用这个特性的例子是:

def get_adder(summand1):
    """Returns a function that adds numbers to a given number."""
    def adder(summand2):
        return summand1 + summand2

    return adder

2.16.2 Pros

经常可以让代码更简明优雅,尤其会让有经验的Lisp和Scheme(以及Haskell和ML还有其他)的程序要很舒服.

2.16.3 Cons

可能会导致令人迷惑的bug例如这个基于PEP-0227的例子.

i = 4
def foo(x):
    def bar():
        print(i, end='')
    # ...
    # A bunch of code here
    # ...
    for i in x:  # Ah, i *is* local to foo, so this is what bar sees i对于foo来说是局部变量,所以在这里就是bar函数所获取的值
        print(i, end='')
    bar()

所以foo([1, 2, 3])会打印1 2 3 3而非1 2 3 4.

2.16.4 建议

可以使用

2.17 函数和方法装饰器

在明显有好处时,谨慎明智的使用，避免@staticmethod，控制使用@classmethod

2.17.1 定义

函数和方法装饰器(也就是@记号).一个常见的装饰器是@property,用于将普通方法转换成动态计算属性.然而装饰器语法也允许用户定义装饰器,尤其对于一些函数my_decorator如下:

class C(object):
    @my_decorator
    def method(self):
        # method body ...

是等效于

class C(object):
    def method(self):
        # method body ...
    method = my_decorator(method)

2.17.2 Pros

能够优雅的对方法进行某种转换,而该转换可能减少一些重复代码并保持不变性等等.

2.17.3 Cons

装饰器可以对函数的参数和返回值任意操作,导致非常隐形的操作行为.此外,装饰器在import的时候就被执行,装饰器代码的实效可能非常难恢复.

2.17.4 建议

在有明显好处的地方谨慎地使用装饰器.装饰器应该和函数遵守相同的import和命名指导规则.装饰器的文档应该清晰地声明该函数为装饰器函数.并且要为装饰器函数编写单元测试.

避免装饰器自身对外部的依赖,(如不要依赖于文件,socket,数据库连接等等),这是由于在装饰器运行的时候(在import时,可能从pydoc或其他工具中)这些外部依赖可能不可用.一个被传入有效参数并调用的装饰器应该(尽可能)保证在任何情况下都可用.

装饰器是一种特殊的”顶级代码”,参见main

永远不要使用@staticmethod,除非不得不整合一个API到一个已有的库,应该写一个模块等级的函数.

只在写一个命名的构造器或者一个类特定的,修改必要的全局状态(例如进程缓存等)的流程时使用@classmethod.

2.18 线程

不要依赖于内建类型的原子性

尽管Python内置数据类型例如字典等似乎有原子性操作,仍有一些罕见情况下,他们是非原子的(比如,如果__hash__或者__eq__被实现为Python方法),就不应该依赖于这些类型的原子性.也不应该依赖于原子变量赋值(因为这依赖于字典)

优先使用Queue模块的Queue类来作为线程之间通讯数据的方式.此外,要是用threading模块和其locking primitives(锁原语).了解条件变量的合理用法以便于使用threading.Condition而非使用更低级的锁.

2.19 过于强大的特性

尽量避免使用

2.19.1 定义

Python是一种非常灵活的语言并且提供了很多新奇的特性,诸如定制元类,访问字节码,动态编译,动态继承,对象父类重定义,import hacks,反射(例如一些对于getattr()的应用),系统内置的修改等等.

2.19.2 Pros

这些是非常强大的语言特性,可以让程序更紧凑

2.19.3 Cons

使用这些新特性是很诱人的.但是并不绝对必要,它们很难读很难理解.也很难debug那些在底层使用了不常见的特性的代码.对于原作者而言可能不是这样,但是再次看代码的时候,可能比更长但是更直接的代码要难.

2.19.4 定义

避免在代码中使用这些特性.

内部使用这些特性的标准库和类是可以使用的(例如abc.ABCMeta,collections.namedtuple,和enum)

2.20 新版本Python: Python3 和从`future`import

Python3已经可用了(译者:目前Python2已经不受支持了),尽管不是每个项目都准备好使用Python3,所有的代码应该兼容Python3并且在可能的情况下在Python3的环境下测试.

2.20.1 定义

Python3是Python的重大改变,尽管现有代码通常是Python2.7写成的,但可以做一些简单的事情来让代码更加明确地表达其意图,从而可以让代码更好地在Python3下运行而不用调整.

2.20.2 Pros

在考虑Python3编写的代码更清晰明确，一旦所有依赖已就绪，就可以更容易在Python3环境下运行.

2.20.3 Cons

一些人会认为默认样板有些丑,import实际不需要的特性到模块中是不常见的.

2.20.4 建议

from future imports

鼓励使用from __future__ import语句.所有新代码都应该包含下述代码,而现有代码应该被更新以尽可能兼容:

from __future__ import absolute_import
from __future__ import division
from __future__ import print_function

如果你不太熟悉这些,详细阅读这些:绝对import,新的/除法行为,和print函数

请勿省略或移除这些import,即使在模块中他们没有在使用,除非代码只用于Python3.最好总是在所有的文档中都有从future的import,来保证不会在有人使用在后续编辑时遗忘.

有其他的from __future__import语句,看喜好使用.我们的建议中不包含unicode_literals因为其并无明显优势,这是由于隐式默认的编码转换导致其在Python2.7内很多地方被引入了,必要时,大多数代码最好显式的使用b''和u''btyes和unicode字符串表示.(译者:这段翻译可能不准确)

The six, future, or past libraries

当项目需要支持Python2和3时,根据需求使用six,future和past.

2.21 带有类型注释的代码

可以根据PEP-484对Python3代码进行类型注释,并且在build时用类型检查工具例如pytype进行类型检查.

类型注释可以在源码中或stub pyi file中.只要可能,注释就应写在源代码中.对于第三方或拓展模块使用pyi文件.

2.21.1 定义

类型注释(也称为”类型提示”)是用于函数或方法参数和返回值的:

def func(a: int) -> List[int]:

你也可以声明用一个单独的注释来声明变量的类型:

a = SomeFunc()  # type: SomeType

2.21.2 Pros

类型注释提升代码的可读性和可维护性,类型检查会将很多运行错误转化为构建错误,也减少了使用过于强力特性的能力.

2.21.3 Cons

需要不断更新类型声明,对于认为有效的代码可能会报类型错误,使用类型检查可能减少使用过于强力特性的能力.

2.21.4 建议

强烈鼓励在更新代码的时候进行Python类型分析.在对公共API进行补充和修改时,包括python类型声明并通过构建系统中的pytype进行检查.对Python来说静态类型检查比较新,我们承认,一些意料外的副作用(例如错误推断的类型)可能拒绝一些项目的使用.这种情况下,鼓励作者适当地增加一个带有TODO或到bug描述当前不接搜的类型注释的链接到BUILD文件或者在代码内.

3、Python代码风格规范

3.1 分号

不要在行尾加分号，也不要用分号把两行语句合并到一行

3.2 行长度

最大行长度是80个字符

超出80字符的明确例外:

长import
注释中的：URL,路径,flags等
不包含空格不方便分行的模块级别的长字符串常量
pylint的diable注释使用(如# pylint: disable=invalid-name)

不要使用反斜杠连接,除非对于需要三层或以上的上下文管理器with语句

利用Python的implicit line joining inside parentheses, brackets and braces(隐式行连接方法–括号连接,包括(), [], {}).如果必要的话,也可在表达式外面额外添加一对括号.

Yes:

foo_bar(self, width, height, color='black', design=None, x='foo',
        emphasis=None, highlight=0)

if (width == 0 and height == 0 and
    color == 'red' and emphasis == 'strong'):

当字符串不能在一行内完成时,使用括号来隐式连接行:

x = ('This will build a very long long '
     'long long long long long long string')

在注释内,如有必要,将长URL放在其本行内:

Yes:

# See details at
# http://www.example.com/us/developer/documentation/api/content/v2.0/csv_file_name_extension_full_specification.html

No:

# See details at
# http://www.example.com/us/developer/documentation/api/content/\
# v2.0/csv_file_name_extension_full_specification.html

在定义一个表达式超过三行或更多的with语句时,可以使用反斜杠来分行.对于两行表达式,使用嵌套with语句:

Yes:

with very_long_first_expression_function() as spam, \
     very_long_second_expression_function() as beans, \
     third_thing() as eggs:
    place_order(eggs, beans, spam, beans)

with very_long_first_expression_function() as spam:
    with very_long_second_expression_function() as beans:
        place_order(beans, spam)

No:

with VeryLongFirstExpressionFunction() as spam, \
     VeryLongSecondExpressionFunction() as beans:
    PlaceOrder(eggs, beans, spam, beans)

注意上述例子中的缩进,具体参看缩进

在其他一行超过80字符的情况下,而且yapf自动格式工具也不能使分行符合要求时,允许超过80字符限制.

3.3 括号

括号合理使用

尽管不必要,但是可以在元组外加括号.再返回语句或者条件语句中不要使用括号,除非是用于隐式的连接行或者指示元组.

Yes:

if foo:
    bar()
while x:
    x = bar()
if x and y:
    bar()
if not x:
    bar()
# For a 1 item tuple the ()s are more visually obvious than the comma.
onesie = (foo,)
return foo
return spam, beans
return (spam, beans)
for (x, y) in dict.items(): ...

No:

if (x):
    bar()
if not(x):
    bar()
return (foo)

3.4 缩进

缩进用4个空格

缩进代码段不要使用制表符,或者混用制表符和空格.如果连接多行,多行应垂直对齐,或者再次4空格缩进(这个情况下首行括号后应该不包含代码).

Yes:

# Aligned with opening delimiter
# 和opening delimiter对齐(译者理解是分隔符的入口,例如三种括号,字符串引号等)
foo = long_function_name(var_one, var_two,
                         var_three, var_four)
meal = (spam,
        beans)

# Aligned with opening delimiter in a dictionary
foo = {
    long_dictionary_key: value1 +
                         value2,
    ...
}

# 4-space hanging indent; nothing on first line
# 缩进4个空格,首行括号后无内容
foo = long_function_name(
    var_one, var_two, var_three,
    var_four)
meal = (
    spam,
    beans)

# 4-space hanging indent in a dictionary
foo = {
    long_dictionary_key:
        long_dictionary_value,
    ...
}

No:

# Stuff on first line forbidden
# 首行不允许有内容
foo = long_function_name(var_one, var_two,
    var_three, var_four)
meal = (spam,
    beans)

# 2-space hanging indent forbidden
foo = long_function_name(
  var_one, var_two, var_three,
  var_four)

# No hanging indent in a dictionary
foo = {
    long_dictionary_key:
    long_dictionary_value,
    ...
}

3.4.1 关于尾后逗号

关于在一序列元素中的尾号逗号,只推荐在容器结束符号],)或者}和最后元素不在同一行时使用.尾后逗号的存在也被用作我们Python代码自动格式化工具yapf的提示,在,最后元素之后出现的时候来自动调整容器元素到每行一个元素.

Yes:

golomb3 = [0, 1, 3]
golomb4 = [
    0,
    1,
    4,
    6,
]

No:

golomb4 = [
    0,
    1,
    4,
    6
]

3.5 空行

在顶级定义(函数或类)之间要间隔两行.在方法定义之间以及class所在行与第一个方法之间要空一行,def行后无空行,在函数或方法内你认为合适地方可以使用单空行.

3.6 空格

遵守标准的空格和标点排版规则.

括号(),[],{}内部不要多余的空格.

Yes:

spam(ham[1], {eggs: 2}, [])

No:

spam( ham[ 1 ], { eggs: 2 }, [ ] )

逗号、分号、冒号前不要空格,但是在后面要加空格,除非是在行尾.

Yes:

if x == 4:
    print(x, y)
x, y = y, x

No:

if x == 4 :
    print(x , y)
x , y = y , x

在函数调用括号的前,索引切片括号前都不加空格.

Yes:

spam(1)
dict['key'] = list[index]

No:

spam (1)
dict ['key'] = list [index]

行尾不要加空格.

在赋值(=),比较(==,<,>,!=,<>,<=,>=,in,not in,is,is not),布尔符号(and,or,not)前后都加空格.视情况在算术运算符(+,-,*,/,//,%,**,@),前后加空格

Yes:

x == 1

No:

x<1

在关键字名参数传递或定义默认参数值的时候不要在=前后加空格,只有一个例外:当类型注释存在时在定义默认参数值时=前后加空格

Yes:

def complex(real, imag=0.0): return Magic(r=real, i=imag)
def complex(real, imag: float = 0.0): return Magic(r=real, i=imag)

No:

def complex(real, imag = 0.0): return Magic(r = real, i = imag)
def complex(real, imag: float=0.0): return Magic(r = real, i = imag)

不要用空格来做无必要的对齐,因为这会在维护时带来不必要的负担(对于:.#,=等等).

Yes:

foo = 1000  # comment
long_name = 2  # comment that should not be aligned
dictionary = {
    'foo': 1,
    'long_name': 2,
}

No:

foo       = 1000  # comment
long_name = 2     # comment that should not be aligned

dictionary = {
    'foo'      : 1,
    'long_name': 2,
}

3.7 Shebang

大部分.py文件不需要从#!行来开始.根据PEP-394,程序的主文件应该以#!/usr/bin/python2或#!/usr/bin/python3起始

这行被用于帮助内核找到Python解释器,但是在导入模块时会被Python忽略/只在会被直接运行的文件里有必要写.

3.8 注释和文档字符串

确保使用正确的模块,函数,方法的文档字符串和行内注释.

3.8.1 文档字符串

Python使用文档字符串来为代码生成文档.文档字符串是包,模块,类或函数的首个语句.这些字符串能够自动被__doc__成员方法提取并且被pydoc使用.(尝试在你的模块上运行pydoc来看看具体是什么).文档字符串使用三重双引号"""(根据PEP-257).文档字符串应该这样组织:一行总结(或整个文档字符串只有一行)并以句号,问好或感叹号结尾.随后是一行空行,随后是文档字符串,并与第一行的首个引号位置相对齐.更多具体格式规范如下.

3.8.2 模块

每个文件都应包含许可模板.选择合适的许可模板用于项目(例如Apache 2.0,BSD,LGPL,GPL)

文档应该以文档字符串开头,并描述模块的内容和使用方法.

"""A one line summary of the module or program, terminated by a period.

Leave one blank line.  The rest of this docstring should contain an
overall description of the module or program.  Optionally, it may also
contain a brief description of exported classes and functions and/or usage
examples.

  Typical usage example:

  foo = ClassFoo()
  bar = foo.FunctionBar()
"""

3.8.3 函数和方法

在本节,”函数”所指包括方法,函数或者生成器.

函数应有文档字符串,除非符合以下所有条件:

外部不可见
非常短
简明

文档字符串应该包含足够的信息以在无需阅读函数代码的情况下调用函数.文档字符串应该是叙事体("""Fetches rows from a Bigtable.""")的而非命令式的("""Fetch rows from a Bigtable."""),除了@property(应与attribute使用同样的风格).文档字符串应描述函数的调用语法和其意义,而非实现.对比较有技巧的地方,在代码中使用注释更合适.

覆写了基类的方法可有简单的文档字符串向读者指示被覆写方法的文档字符串例如"""See base class.""".这是因为没必要在很多地方重复已经在基类的文档字符串中存在的文档.不过如果覆写的方法行为实际上与被覆写方法不一致,或者需要提供细节(例如文档中表明额外的副作用),覆写方法的文档字符串至少要提供这些差别.

一个函数的不同方面应该在特定对应的分节里写入文档,这些分节如下.每一节都由以冒号结尾的一行开始, 每一节除了首行外,都应该以2或4个空格缩进并在整个文档内保持一致(译者建议4个空格以维持整体一致).如果函数名和签名足够给出足够信息并且能够刚好被一行文档字符串所描述,那么可以忽略这些节.

Args:

列出每个参数的名字.名字后应有为冒号和空格,后跟描述.如果描述太长不能够在80字符的单行内完成.那么分行并缩进2或4个空格且与全文档一致(译者同样建议4个空格)

描述应该包含参数所要求的类型,如果代码不包含类型注释的话.如果函数容许*foo(不定长度参数列表)或**bar(任意关键字参数).那么就应该在文档字符串中列举为*foo和**bar.

Returns:(或对于生成器是Yields:)

描述返回值的类型和含义.如果函数至少返回None,这一小节不需要.如果文档字符串以Returns或者Yields开头(例如"""Returns row from Bigtable as a tuple of strings.""")或首句足够描述返回值的情况下这一节可忽略.

Raises:

列出所有和接口相关的异常.对于违反文档要求而抛出的异常不应列出.(因为这会矛盾地使得违反接口要求的行为成为接口的一部分)

def fetch_bigtable_rows(big_table, keys, other_silly_variable=None):
    """Fetches rows from a Bigtable.

    Retrieves rows pertaining to the given keys from the Table instance
    represented by big_table.  Silly things may happen if
    other_silly_variable is not None.

    Args:
        big_table: An open Bigtable Table instance.
        keys: A sequence of strings representing the key of each table row
            to fetch.
        other_silly_variable: Another optional variable, that has a much
            longer name than the other args, and which does nothing.

    Returns:
        A dict mapping keys to the corresponding table row data
        fetched. Each row is represented as a tuple of strings. For
        example:

        {'Serak': ('Rigel VII', 'Preparer'),
         'Zim': ('Irk', 'Invader'),
         'Lrrr': ('Omicron Persei 8', 'Emperor')}

        If a key from the keys argument is missing from the dictionary,
        then that row was not found in the table.

    Raises:
        IOError: An error occurred accessing the bigtable.Table object.
    """

3.8.4 类

类定义下一行应为描述这个类的文档字符串.如果类有公共属性,应该在文档字符串中的Attributes节中注明,并且和函数的Args一节风格统一.

class SampleClass(object):
    """Summary of class here.

    Longer class information....
    Longer class information....

    Attributes:
        likes_spam: A boolean indicating if we like SPAM or not.
        eggs: An integer count of the eggs we have laid.
    """

    def __init__(self, likes_spam=False):
        """Inits SampleClass with blah."""
        self.likes_spam = likes_spam
        self.eggs = 0

    def public_method(self):
        """Performs operation blah."""

3.8.5 块注释和行注释

最后要在代码中注释的地方是代码技巧性的部分.如果你将要在下次code review中揭示代码.应该现在就添加注释.在复杂操作开始前,注释几行.对于不够明晰的代码在行尾注释.

# We use a weighted dictionary search to find out where i is in
# the array.  We extrapolate position based on the largest num
# in the array and the array size and then do binary search to
# get the exact number.
if i & (i-1) == 0:  # True if i is 0 or a power of 2.

为了提升易读性,行注释应该至少在代码2个空格后,并以#后接至少1个空格开始注释部分.

另外,不要描述代码,假定阅读代码的人比你更精通Python(他只是不知道你试图做什么).

3.8.6 标点,拼写和语法

注意标点,拼写和语法,写得好的注释要比写得差的好读.

注释应当是和叙事性文本一样可读,并具有合适的大小写和标点.在许多情况下,完整的句子要比破碎的句子更可读.更简短的注释如行尾的注释有时会不太正式,但是应该全篇保持风格一致.

尽管被代码审核人员指出在应该使用分号的地方使用了逗号是很令人沮丧的,将源代码维护在高度清楚可读的程度是很重要的.合适的标点,拼写和语法能够帮助达到这个目标.

3.9 类

如果类并非从其他基类继承而来,那么就要明确是从object继承而来,即便内嵌类也是如此.

Yes:

class SampleClass(object):
    pass

class OuterClass(object):
    class InnerClass(object):
        pass

class ChildClass(ParentClass):
    """Explicitly inherits from another class already."""

No:

class SampleClass:
    pass

class OuterClass:
    class InnerClass:
        pass

从object类继承保证了属性能够在Python2正确运行并且保护代码在Python3下出现潜在的不兼容.这样也定义了object包括__new__,__init__,__delattr__,__getattribute__,__setattr__,__hash__,__repr__,和__str__等默认特殊方法的实现.

3.10 字符串

使用format或%来格式化字符串,即使参数都是字符串对象,也要考虑使用+还是%及format.

Yes:

x = a + b
x = '%s, %s!' % (imperative, expletive)
x = '{}, {}'.format(first, second)
x = 'name: %s; score: %d' % (name, n)
x = 'name: {}; score: {}'.format(name, n)
x = f'name: {name}; score: {n}'  # Python 3.6+

No:

employee_table = '<table>'
for last_name, first_name in employee_list:
    employee_table += '<tr><td>%s, %s</td></tr>' % (last_name, first_name)
employee_table += '</table>'

避免使用+和+=操作符来在循环内累加字符串,因为字符串是不可变对象.这会造成不必要的临时变量导致运行时间以四次方增长而非线性增长.应将每个字符串都记入一个列表并使用''.join来将列表在循环结束后连接(或将每个子字符串写入io.BytesIO缓存)

Yes:

items = ['<table>']
for last_name, first_name in employee_list:
    items.append('<tr><td>%s, %s</td></tr>' % (last_name, first_name))
items.append('</table>')
employee_table = ''.join(items)

No:

employee_table = '<table>'
for last_name, first_name in employee_list:
    employee_table += '<tr><td>%s, %s</td></tr>' % (last_name, first_name)
employee_table += '</table>'

在同一个文件内,字符串引号要一致,选择''或者""并且不要改变.对于需要避免\\转义的时候,可以更改.

Yes:

Python('Why are you hiding your eyes?')
Gollum("I'm scared of lint errors.")
Narrator('"Good!" thought a happy Python reviewer.')

No:

Python("Why are you hiding your eyes?")
Gollum('The lint. It burns. It burns us.')
Gollum("Always the great lint. Watching. Watching.")

多行字符串多行字符串优先使用”””而非''',当且只当对所有非文档字符串的多行字符串都是用'''而且对正常字符串都使用'时才可使用三单引号.docstring不论如何必须使用"""

多行字符串和其余代码的缩进方式不一致.如果需要避免在字符串中插入额外的空格,要么使用单行字符串连接或者带有textwarp.dedent()的多行字符串来移除每行的起始空格.

No:

long_string = """This is pretty ugly.
Don't do this.
"""

Yes:

long_string = """This is fine if your use case can accept
    extraneous leading spaces."""

long_string = ("And this is fine if you can not accept\n" +
               "extraneous leading spaces.")

long_string = ("And this too is fine if you can not accept\n"
               "extraneous leading spaces.")

import textwrap

long_string = textwrap.dedent("""\
    This is also fine, because textwrap.dedent()
    will collapse common leading spaces in each line.""")

3.11 文件和socket

当使用结束后显式地关闭文件或socket.

不必要地打开文件，socket或其他类似文件的对象有很多弊端：

他们可能会消耗有限的系统资源,例如文件描述符.如果在使用没有即使归还系统,处理很多这样对象的代码可能会浪费掉很多不应浪费的资源.
保持一个文件可能会阻止其他操作诸如移动或删除.
被程序共享的文件和socket可能会无意中在逻辑上已被关闭的情况下仍被读写.如果实际上已经关闭,试图读写的操作会抛出异常,这样就可以立即发现问题.

此外,当文件或socket在文件对象被销毁的同时被自动关闭的时候,是不可能将文件的生命周期和文件状态绑定的:

不能保证何时会真正将文件对象销毁.不同的Python解释器使用的内存管理技术不同,例如延时垃圾处理可能会让对象的生命周期被无限期延长.
可能导致意料之外地对文件对象的引用,例如在全局变量或者异常回溯中,可能会让文件对象比预计的生命周期更长.

推荐使用with语句管理文件:

with open("hello.txt") as hello_file:
    for line in hello_file:
        print(line)

对于类似文件的对象,如果不支持with语句的可以使用contextlib.closing():

import contextlib

with contextlib.closing(urllib.urlopen("http://www.python.org/")) as front_page:
    for line in front_page:
        print(line)

3.12 TODO注释

对于下述情况使用TODO注释:临时的,短期的解决方案或者足够好但是不完美的解决方案.

TODO注释以全部大写的字符串TODO开头,并带有写入括号内的姓名,email地址,或其他可以标识负责人或者包含关于问题最佳描述的issue.随后是这里做什么的说明.

有统一风格的TODO的目的是为了方便搜索并了解如何获取更多相关细节.TODO并不是保证被提及者会修复问题.因此在创建TODO注释的时候,基本上都是给出你的名字.

# TODO(kl@gmail.com): Use a "*" here for string repetition.
# TODO(Zeke) Change this to use relations.

如果TODO注释形式为”未来某个时间点会做什么事”的格式,确保要么给出一个非常具体的时间点(例如”将于2009年11月前修复”)或者给出一个非常具体的事件(例如”当所有客户端都能够处理XML响应时就移除此代码”).

3.13 import格式

imports应该在不同行.例如:

Yes:

import os
import sys

No:

import os, sys

import应集中放在文件顶部,在模块注释和docstring后面,模块globals和常量前面.应按照从最通用到最不通用的顺序排列分组:

Python未来版本import语句,例如:

from __future__ import absolute_import
from __future__ import division
from __future__ import print_function

更多信息参看上文

Python标准基础库import,例如:
```
import sys
```
第三方库或包的import,例如:
```
import tensorflow as tf
```
代码库内子包import,例如:
```
from otherproject.ai import mind
```
此条已弃用:和当前文件是同一顶级子包专用的import,例如:
```
from myproject.backend.hgwells import time_machine
```
在旧版本的谷歌Python代码风格指南中实际上是这样做的.但是现在不再需要了.**新的代码风格不再受此困扰.**简单的将专用的子包import和其他子包import同一对待即可.

在每个组内按照每个模块的完整包路径的字典序忽略大小写排序.可以根据情况在每个节质检增加空行.

import collectionsimport queueimport sys

from absl import appfrom absl import flagsimport bs4import cryptographyimport tensorflow as tf

from book.genres import scififrom myproject.backend.hgwells import time_machinefrom myproject.backend.state_machine import main_loopfrom otherproject.ai import bodyfrom otherproject.ai import mindfrom otherproject.ai import soul

# Older style code may have these imports down here instead:
# 旧版本代码风格可能会采用下述import方式
# from myproject.backend.hgwells import time_machine
# from myproject.backend.state_machine import main_loop

3.14 语句

每行只有一条语句.

不过如果测试语句和结果能够在一行内放下,就可以放在一行内.但是不允许将try/except语句和对应内容放于一行,因为try或者except都不能在一行内完成.对于没有else的if语句可以将if和对应内容合并到一行.

Yes:

if foo: bar(foo)

No:

if foo: bar(foo)
else:   baz(foo)

try:               bar(foo)
except ValueError: baz(foo)

try:
    bar(foo)
except ValueError: baz(foo)

3.15 访问

对于琐碎又不太重要的访问函数,应用公共变量来替代访问函数,以避免额外的程序调用消耗,当添加了更多函数功能时,使用property来保持连续性

此外,如果访问过于复杂,或者访问变量的消耗过大,应该使用诸如get_foo()和set_foo()之类的函数式访问(参考命名指南).如果过去的访问方式是通过属性,新访问函数不要绑定到property上,这样使用property的旧方式就会失效,使用者就会知道函数有变化.

3.16 命名

module_name,package_name,ClassName,method_name,ExceptionName,function_name,GLOBAL_CONSTANT_NAME,global_var_name,instance_var_name,function_parameter_name,local_var_name.

命名函数名,变量名,文件名应该是描述性的,避免缩写,尤其避免模糊或对读者不熟悉的缩写.并且不要通过删减单词内的字母来缩短.

使用.py作为文件拓展名,不要使用横线.

3.16.1 要避免的名字：

单字符名字,除非是计数或迭代元素,e可以作为Exception捕获识别名来使用..
-横线,不应出现在任何包名或模块名内
__double_leading_and_trailing_underscore__首尾都双下划线的名字,这种名字是python的内置保留名字

3.16.4 命名约定

internal表示仅模块内可用、或者类内保护的或者私有的
单下划线(_)开头表示是被保护的(from module import *不会import).双下划线(__也就是”dunder”)开头的实例变量或者方法表示类内私有(使用命名修饰).我们不鼓励使用,因为这会对可读性和可测试性有削弱二期并非真正的私有.
相关的类和顶级函数放在同一个模块内,不必像是Java一样要一个类放在一个模块里.
对类名使用大写字母(如CapWords)开头的单词,命名,模块名应该使用小写加下划线的方式.尽管有一些旧的模块命名方式是大写字母的(如CapWords.py),现在不鼓励这样做了,因为在模块刚好是从某个类命名出发的时候可能会令人迷惑(例如是选择import StringIO还是from StringIO import StringIO?)
在unittest方法中可能是test开头来分割名字的组成部分,即使这些组成部分是使用大写字母驼峰式的.这种方式是可以的：test<MethodUnderTest>_<state>例如testPop_EmptyStack,对于命名测试方法没有明确的正确方法.

3.16.3 文件名

文件拓展名必须为.py,不可以包含-.这保证了能够被正常import和单元测试.如果希望一个可执行文件不需要拓展名就可以被调用,那么建立一个软连接或者一个简单的bash打包脚本包括exec "$0.py" "$@".

3.16.4 Guido的指导建议

类型	公共	内部
包	`lower_with_under`
模块	`lower_with_under`	`_lower_with_under`
类	`CapWords`	`_CapWords`
异常	`CapWords`
函数	`lower_with_under()`	`_lower_with_under()`
全局/类常量	`CAPS_WITH_UNDER`	`_CAPS_WITH_UNDER`
全局/类变量	`lower_with_under`	`_lower_with_under`
实例变量	`lower_with_under`	`_lower_with_under`(受保护)
方法名	`lower_with_under()`	`_lower_with_under()`(受保护)
函数/方法参数	`lower_with_under`
局部变量	`lower_with_under`

尽管Python支持通过双下划线__(即”dunder”)来私有化.不鼓励这样做.优先使用单下划线.单下划线更易于打出来、易读、易于小的单元测试调用.Lint的警告关注受保护成员的无效访问.

3.17 Main

即便是一个用做脚本的py文件也应该是可以被import的,而只用于import时,也不应有执行了主函数的副作用.主函数的功能应该被放在main()里.

在Python中,pydoc和单元测试要求模块是可import的.所以代码在主程序执行前应进行if __name__ == '__main__':检查,以防止模块在import时被执行.

def main():
    ...

if __name__ == '__main__':
    main()

所有顶级代码在模块被import时执行.因而要小心不要调用函数,创建对象或者执行其他在执行pydoc时不应该被执行的操作.

3.18 函数长度

优先写小而专一的函数.

长函数有时候是合适的,故而函数长度没有固定的限制.但是超过40行的时候就要考虑是否要在不影响程序结构的前提下分解函数.

尽管长函数现在运行的很好,但是在之后的时间里其他人修改函数并增加新功能的时候可能会引入新的难以发现的bug,保持函数的简短,这样有利于其他人读懂和修改代码.

在处理一些代码时,可能会发现有些函数长而且复杂.不要畏惧调整现有代码,如果处理这个函数非常困难,如难以对报错debug或者希望在几个不同的上下文中使用它,那么请将函数拆解成若干个更小更可控的片段.

3.19 类型注释

3.19.1 基本规则

熟悉PEP-484
在方法中,只在必要时给self或者cls增加合适的类型信息.例如@classmethod def create(cls: Type[T]) -> T: return cls()
如果其他变量或返回类型不定,使用Any
不需要注释每个函数
- 至少需要注明公共接口
- 使用类型检查来在安全性和声明清晰性以及灵活性之间平衡
- 标注容易因类型相关而抛出异常的代码(previous bugs or complexity,此处译者认为是与上一条一致,平衡安全性和复杂性)
- 标注难理解的代码
- 标注类型稳定的代码,成熟稳定的代码可以都进行标注而不会影响其灵活性

3.19.2 分行

遵循现有的缩进规范

标注类型后,函数签名多数都要是”每行一个参数”.

def my_method(self,
              first_var: int,
              second_var: Foo,
              third_var: Optional[Bar]) -> int:
  ...

优先在变量之间换行,而非其他地方(如变量名和类型注释之间).如果都能放在一行内,就放在一行.

def my_method(self, first_var: int) -> int:
  ...

如果函数名,一直到最后的参数以及返回类型注释放在一行过长,那么分行并缩进4个空格.

def my_method(
    self, first_var: int) -> Tuple[MyLongType1, MyLongType1]:
  ...

当返回值类型不能和最后一个参数放入同一行,比较好的处理方式是将参数分行并缩进4个空格,右括号和返回值类型换行并和def对齐.

def my_method(
    self, other_arg: Optional[MyLongType]
) -> Dict[OtherLongType, MyLongType]:
  ...

pylint允许您将右括号移动到新行并与左括号对齐,但这不太容易理解.

No:

def my_method(self,
              other_arg: Optional[MyLongType]
             ) -> Dict[OtherLongType, MyLongType]:
  ...

就像上面的例子一样,尽量不要分割类型注释,不过有时类型注释太长无法放入一行,(那就尽量让子注释不要被分割).

def my_method(
    self,
    first_var: Tuple[List[MyLongType1],
                     List[MyLongType2]],
    second_var: List[Dict[
        MyLongType3, MyLongType4]]) -> None:
  ...

如果某个命名和类型太长了,考虑使用别名.如果没有其他解决方案,在冒号后分行缩进4个空格.

Yes:

def my_function(
    long_variable_name:
        long_module_name.LongTypeName,
) -> None:
  ...

No:

def my_function(
    long_variable_name: long_module_name.
        LongTypeName,) -> None:
  ...

3.19.3 前置声明

如果需要同一模块内还未定义的类名,例如需要类声明内部的类,或者需要在后续代码中定义的类,那么使用类名的字符串来代替.

class MyClass(object):

  def __init__(self,
               stack: List["MyClass"]) -> None:

3.19.4 默认值

参考PEP-008,只有在同时需要类型注释和默认值的时候在=前后都加空格

Yes:

def func(a: int = 0) -> int:
  ...

No:

def func(a:int=0) -> int:
  ...

3.19.5 NoneType

在Python系统中NoneType是一等类型,为了方便输入,None是NoneType的别名.如果一个参数可以是None,那么就需要声明!可以使用Union,但如果只有一个其他类型,那么使用Optional.

显式地使用Optional而非隐式地.PEP 484的早期版本容许a: Text = None被解释为a: Optional[Text] = None.但现在已经不推荐这样使用了.

Yes:

def func(a: Optional[Text], b: Optional[Text] = None) -> Text:
  ...
def multiple_nullable_union(a: Union[None, Text, int]) -> Text
  ...

No:

def nullable_union(a: Union[None, Text]) -> Text:
  ...
def implicit_optional(a: Text = None) -> Text:
  ...

3.19.6 类型别名

可以对复杂类型声明别名,别名的名称应为CapWorded,如果只用于当前模块,应加下划线私有化.

例如,如果带有模块名的类型名过长:

_ShortName = module_with_long_name.TypeWithLongName
ComplexMap = Mapping[Text, List[Tuple[int, int]]]

其他示例是复杂的嵌套类型和一个函数的多个返回变量（作为元组）.

3.19.7 忽略类型检查

可以通过增加特殊行注释# type: ignore来禁止类型检查.

pytype对于明确的报错有关闭选项(类似于lint):

# pytype: disable=attribute-error

3.19.8 对变量注释类型

对变量标注类型如果内部变量很难或者不可能指向,可以使用下述方式：

类型注释:

在行尾增加以# type开头的注释

a = SomeUndecoratedFunction()  # type: Foo

注释绑定:

在变量名和赋值之间用冒号和类型注明,和函数参数一致.

a: Foo = SomeUndecoratedFunction()

3.19.9 元组和列表

不像是列表只能包含单一类型,元组可以既只有一种重复类型或者一组不同类型的元素,后者常用于函数返回.

a = [1, 2, 3]  # type: List[int]
b = (1, 2, 3)  # type: Tuple[int, ...]
c = (1, "2", 3.5)  # type: Tuple[int, Text, float]

3.19.10 TypeVars

Python是有泛型的,工厂函数TypeVar是通用的使用方式.

例子:

from typing import List, TypeVar
T = TypeVar("T")
...
def next(l: List[T]) -> T:
  return l.pop()

TypeVar可以约束类型:

AddableType = TypeVar("AddableType", int, float, Text)
def add(a: AddableType, b: AddableType) -> AddableType:
    return a + b

在typing模块预定义好的类型变量是AnyStr,用于针对字符串可以是bytes也可为unicode并且保持一致的多个类型注释.

from typing import AnyStr
def check_length(x: AnyStr) -> AnyStr:
  if len(x) <= 42:
    return x
  raise ValueError()

3.19.11 字符串类型

注释字符串的合适类型是基于Python版本的.

对于只有Python3的代码,使用str,Text可以用但是在选择上保持一致.

对于Python2兼容的代码,用Text,在一些很罕见的情况下,str可能可用.当在不同Python版本之间返回值类型不同的时候通常是为了照顾兼容性.避免使用unicode,因为Python3中不存在.

No:

def py2_code(x: str) -> unicode:
  ...

对于处理二进制数据的代码,请使用bytes.

Yes:

def deals_with_binary_data(x: bytes) -> bytes:
  ...

对于Python2兼容,处理文本数据(Python中str或unicode,Python3中str)的代码,使用Text.对于只有Python3的代码,优先使用str.

from typing import Text
...
def py2_compatible(x: Text) -> Text:
  ...
def py3_only(x: str) -> str:
  ...

如果既可以是byte也可以是文本,那么使用Union和合适的文本类型.

from typing import Text, Union
...
def py2_compatible(x: Union[bytes, Text]) -> Union[bytes, Text]:
  ...
def py3_only(x: Union[bytes, str]) -> Union[bytes, str]:
  ...

如果一个函数中所有的字符串类型始终一致,例如前文例子中返回值类型和参数类型是一致的,那么使用AnyStr

像这样写能够简化代码向Python3的迁移过程.

3.19.12 typing的import

对于从typing模块import的类,要import类本身.明确的允许在一行内从typing模块import多个特定的类,如

from typing import Any, Dict, Optional

这种从typing模块import的方式会向命名空间内增加额外项,typing中的任何命名都应该和关键字同等对待并且不在你的Python代码中定义,typed or not(译者推测文无论是否引入).如果和已有的命名冲突,使用import x as y来import.

from typing import Any as AnyType

3.19.13 条件import

只在运行时一定要避免进行类型检查的情况下使用条件import.不鼓励使用这种模式.鼓励使用其他替代方式诸如重构代码以容许顶级import.

只用于类型注释的import可以被归于if TYPE_CHECKING:代码块中.

条件import的类型应被视为字符串引用,以和Python3.6兼容(在Python3.6中,注释表达式实际上被赋值的).
只有单独用于类型注释的实例才能在这里定义,包括了别名.否则将会报运行错误因为在运行时这些模块不会被引用.
代码块应该紧跟在正常import后面.
在类型import后不应有空行
按照正常import顺序对这一块代码进行排序

import typing
if typing.TYPE_CHECKING:
    import sketch
def f(x: "sketch.Sketch"): ...

3.19.14 循环依赖

由于类型检查引发的循环依赖是一种code smell(代码异味),这样的代码应当被重构.尽管技术上是可以保留循环引用的.build system(系统)不允许这样做因为每个模块都要依赖于其他模块.

将造成循环依赖的模块替换为Any并赋予一个有意义的别名并使用从这个模块导入的真实类名(因为任何Any的属性都是Any).别名的定义用和最后一行import用一行空行分隔.

from typing import Any

some_mod = Any  # some_mod.py imports this module.
...

def my_method(self, var: some_mod.SomeType) -> None:
  ...

3.19.15 泛型

当注释的时候,优先泛型类型专有类型参数,否则泛型的参数会被认为是Any.

def get_names(employee_ids: List[int]) -> Dict[int, Any]:
  ...

# These are both interpreted as get_names(employee_ids: List[Any]) -> Dict[Any, Any]
def get_names(employee_ids: list) -> Dict:
  ...

def get_names(employee_ids: List) -> Dict:
  ...

如果泛型最佳的参数类型是Any也将其显式地表示出来.但是在很多情况下TypeVar可能更合适.

def get_names(employee_ids: List[Any]) -> Dict[Any, Text]:
"""Returns a mapping from employee ID to employee name for given IDs."""

T = TypeVar('T')
def get_names(employee_ids: List[T]) -> Dict[T, Text]:
"""Returns a mapping from employee ID to employee name for given IDs."""

4、最后的话

如果你在编辑代码,花几分钟看看现有代码然后决定好要使用哪种风格.如果现有代码在所有算术运算符两侧都加了空格,那么你也应该如此.如果现有的注释用井号组成了包围框,那么你的注释也应如此.

有代码风格指南的目的是有一个编程的共识,这样人们能够集中在内容而非形式上.我们将通用的代码风格指南公布于此这样人们就能了解这个共识(译者:有巴别塔的意味.)但是各自的代码风格也很重要.如果你添加的代码与原有代码看起来完全不一致，就会打乱读者的阅读节奏，最好避免这样。

我们的文章到此就结束啦，如果你喜欢今天的 Python 教程，请持续关注Python实用宝典。

有任何问题，可以在公众号后台回复：加群，回答相应验证信息，进入互助群询问。

原创不易，希望你能在下面点个赞和在看支持我继续创作，谢谢！

我要打赏

Python实用宝典 ( pythondict.com )
不只是一个宝典
欢迎关注公众号：Python实用宝典

1.Excel中做数据透视表

2. pandas 用 pivot_table 做数据透视表

3. 案例说明

1.准备

2.Shodan 注册账号获取API

3.Shodan 基本调用实战教程

4. Shodan 高级使用教程

1. 前言

2. 介绍及安装

3. 实战一下

4. 最后

1.Locust特点

2.安装Locust

3.快速上手

4.脚本解析

小结

1.快速上手

2.Birdseye在Pycharm中集成调试

3.Birdseye在VSCode中集成调试

4.美中不足

一、_用于临时变量

1.1 REPL

1.2 for循环中的_

1.3 元组拆包中的_

1.4 国际化函数

1.5 大数字表示形式

二、var_用于解决命名冲突问题

三、_var用于保护变量

3.1 突破保护属性

四、__var用于私有变量

4.1 突破私有属性

五、__var__用于魔术方法

5.1 Python魔术方法分类

六、总结

认识pip

1、安装pip

2、查看pip版本

3、升级pip

4、获取帮助

5、安装库

6、批量安装库

7、使用wheel文件安装库

8、卸载库

9、升级库

10、查看库信息

11、查看已安装的库

12、将库列表保存到指定文件中

13、查看需要升级的库

14、检查兼容问题

15、下载库到本地

附：更换pip源

1. 前言

2. 介绍

3. 更换源及安装依赖

4. 执行脚本

5. 拓展一下

6. 总结

1、背景

2、Python语言规则

2.1 Lint

2.1.1Definition(以下都译为定义)

2.1.2 Pros

2.1.3 Cons

2.1.4 Decision(以下都译为建议)

2.2 Imports

2.2.1 定义

2.2.2 Pros

2.2.3 Cons

2.2.4 建议

2.3 包

2.3.1 Pros

2.3.2 Cons

2.3.3 建议

2.4 异常

2.4.1 定义

2.4.2 Pros

2.4.3 Cons

2.4.4 建议

2.5 全局变量

2.5.1 定义

一、`_`用于临时变量

二、`var_`用于解决命名冲突问题

三、`_var`用于保护变量

四、`__var`用于私有变量

五、`var`用于魔术方法

2.6 内嵌/局部/内部类和函数