Moshe Zadka 发布的文章

这 12 个步骤能确保成功发布。

你写了一个 Python 库。自己觉着这太棒了!如果让人们能够轻松使用它不是很优雅么?这有一个需要考虑的清单,以及在开源 Python 库时要采取的具体步骤。

1、源码

将代码放在 GitHub 上,这里有很多开源项目,并且人们很容易提交拉取请求。

2、许可证

选择一个开源许可证。一般来说 MIT 许可证是一个挺好的宽容许可证。如果你有特定要求,Creative Common 的选择许可证可以指导你完成其它选择。最重要的是,在选择许可证时要记住三条规则:

  • 不要创建自己的许可证。
  • 不要创建自己的许可证。
  • 不要创建自己的许可证。

3、README

将一个名为 README.rst 的文件(使用 ReStructured Text 格式化)放在项目树的顶层。

GitHub 将像 Markdown 一样渲染 ReStructured Text,而 ReST 在 Python 的文档生态系统中的表现更好。

4、测试

写测试。这对你来说没有用处。但对于想要编写避免破坏相关功能的补丁的人来说,它非常有用。

测试可帮助协作者进行协作。

通常情况下,如果可以用 pytest 运行就最好了。还有其他测试工具 —— 但很少有理由去使用它们。

5、样式

使用 linter 制定样式:PyLint、Flake8 或者带上 --check 的 Black 。除非你使用 Black,否则请确保在一个文件中指定配置选项,并签入到版本控制系统中。

6、API 文档

使用 docstrings 来记录模块、函数、类和方法。

你可以使用几种样式。我更喜欢 Google 风格的 docstrings,但 ReST docstrings 也是一种选择。

Sphinx 可以同时处理 Google 风格和 ReST 的 docstrings,以将零散的文档集成为 API 文档。

7、零散文档

使用 Sphinx。(阅读我们这篇文章。)教程很有用,但同样重要的是要指明这是什么、它有什么好处、它有什么坏处、以及任何特殊的考虑因素。

8、构建

使用 tox 或 nox 自动运行测试和 linter,并构建文档。这些工具支持“依赖矩阵”。这些矩阵往往会快速增长,但你可以尝试针对合理的样本进行测试,例如 Python 版本、依赖项版本以及可能安装的可选依赖项。

9、打包

使用 setuptools 工具。写一个 setup.py 和一个 setup.cfg。如果同时支持 Python 2 和 3,请在 setup.cfg 中指定 universal 格式的 wheel。

tox 或 nox 应该做的一件事是构建 wheel 并对已安装的 wheel 进行测试。

避免使用 C 扩展。如果出于性能或绑定的原因一定需要它们,请将它们放在单独的包中。正确打包 C 扩展可以写一篇新的文章。这里有很多问题!

10、持续集成

使用公共持续工具。TravisCICircleCI 为开源项目提供免费套餐。将 GitHub 或其他仓库配置为在合并拉请求之前需要先通过检查,那么你就不必担心在代码评审中告知用户修复测试或样式。

11、版本

使用 SemVerCalVer。有许多工具可以帮助你管理版本:incrementalbumpversionsetuptools\_scm 等都是 PyPI 上的包,都可以帮助你管理版本。

12、发布

通过运行 tox 或 nox 并使用 twine 将文件上传到 PyPI 上发布。你可以通过在 DevPI 中“测试上传”。


via: https://opensource.com/article/18/12/tips-open-sourcing-python-libraries

作者:Moshe Zadka 选题:lujun9972 译者:geekpi 校对:wxy

本文由 LCTT 原创编译,Linux中国 荣誉推出

使用此框架编写断言,提高开发测试的准确性。

测试金字塔的底部是单元测试。单元测试每次只测试一个代码单元,通常是一个函数或方法。

通常,设计单个单元测试是为了测试通过一个函数或特定分支的特定执行流程,这使得将失败的单元测试和导致失败的 bug 对应起来变得容易。

理想情况下,单元测试很少使用或不使用外部资源,从而隔离它们并使它们更快。

单元测试套件通过在开发过程的早期发现问题来帮助维护高质量的产品。有效的单元测试可以在代码离开开发人员机器之前捕获 bug,或者至少可以在特定分支上的持续集成环境中捕获 bug。这标志着好的和坏的单元测试之间的区别:好的测试通过尽早捕获 bug 并使测试更快来提高开发人员的生产力。坏的测试降低了开发人员的工作效率。

当测试附带的特性时,生产率通常会降低。当代码更改时测试会失败,即使它仍然是正确的。发生这种情况是因为输出的不同,但在某种程度上是因为它不是 函数契约 function’s contract 的一部分。

因此,一个好的单元测试可以帮助执行函数所提交的契约。

如果单元测试中断,那意味着该契约被违反了,应该(通过更改文档和测试)明确修改,或者(通过修复代码并保持测试不变)来修复。

虽然将测试限制为只执行公共契约是一项需要学习的复杂技能,但有一些工具可以提供帮助。

其中一个工具是 Hamcrest,这是一个用于编写断言的框架。最初是为基于 Java 的单元测试而发明的,但它现在支持多种语言,包括 Python

Hamcrest 旨在使测试断言更容易编写和更精确。

def add(a, b):
    return a + b

from hamcrest import assert_that, equal_to

def test_add():
    assert_that(add(2, 2), equal_to(4))  

这是一个用于简单函数的断言。如果我们想要断言更复杂的函数怎么办?

def test_set_removal():
    my_set = {1, 2, 3, 4}
    my_set.remove(3)
    assert_that(my_set, contains_inanyorder([1, 2, 4]))
    assert_that(my_set, is_not(has_item(3)))

注意,我们可以简单地断言其结果是任何顺序的 124,因为集合不保证顺序。

我们也可以很容易用 is_not 来否定断言。这有助于我们编写精确的断言,使我们能够把自己限制在执行函数的公共契约方面。

然而,有时候,内置的功能都不是我们真正需要的。在这些情况下,Hamcrest 允许我们编写自己的 匹配器 matchers

想象一下以下功能:

def scale_one(a, b):
    scale = random.randint(0, 5)
    pick = random.choice([a,b])
    return scale * pick

我们可以自信地断言其结果均匀地分配到至少一个输入。

匹配器继承自 hamcrest.core.base_matcher.BaseMatcher,重写两个方法:

class DivisibleBy(hamcrest.core.base_matcher.BaseMatcher):
    def __init__(self, factor):
        self.factor = factor

    def _matches(self, item):
        return (item % self.factor) == 0

    def describe_to(self, description):
        description.append_text('number divisible by')
        description.append_text(repr(self.factor))

编写高质量的 describe_to 方法很重要,因为这是测试失败时显示的消息的一部分。

def divisible_by(num):
    return DivisibleBy(num)

按照惯例,我们将匹配器包装在一个函数中。有时这给了我们进一步处理输入的机会,但在这种情况下,我们不需要进一步处理。

def test_scale():
    result = scale_one(3, 7)
    assert_that(result,
                any_of(divisible_by(3),
                divisible_by(7)))

请注意,我们将 divisible_by 匹配器与内置的 any_of 匹配器结合起来,以确保我们只测试函数提交的内容。

在编辑这篇文章时,我听到一个传言,取 “Hamcrest” 这个名字是因为它是 “matches” 字母组成的字谜。嗯…

>>> assert_that("matches", contains_inanyorder(*"hamcrest")
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
  File "/home/moshez/src/devops-python/build/devops/lib/python3.6/site-packages/hamcrest/core/assert_that.py", line 43, in assert_that
    _assert_match(actual=arg1, matcher=arg2, reason=arg3)
  File "/home/moshez/src/devops-python/build/devops/lib/python3.6/site-packages/hamcrest/core/assert_that.py", line 57, in _assert_match
    raise AssertionError(description)
AssertionError:
Expected: a sequence over ['h', 'a', 'm', 'c', 'r', 'e', 's', 't'] in any order
      but: no item matches: 'r' in ['m', 'a', 't', 'c', 'h', 'e', 's']

经过进一步的研究,我找到了传言的来源:它是 “matchers” 字母组成的字谜。

>>> assert_that("matchers", contains_inanyorder(*"hamcrest"))
>>>

如果你还没有为你的 Python 代码编写单元测试,那么现在是开始的好时机。如果你正在为你的 Python 代码编写单元测试,那么使用 Hamcrest 将允许你使你的断言更加精确,既不会比你想要测试的多也不会少。这将在修改代码时减少误报,并减少修改工作代码的测试所花费的时间。


via: https://opensource.com/article/18/8/robust-unit-tests-hamcrest

作者:Moshe Zadka 选题:lujun9972 译者:MjSeven 校对:wxy

本文由 LCTT 原创编译,Linux中国 荣誉推出

Beamer 将 LaTeX 强大的排版功能和生态系统带进创建幻灯片中。

Beamer 是用于生成幻灯片的 LaTeX 包。它最棒的功能之一是它可以利用 LaTeX 强大的排版系统和其生态系统中的所有其他软件包。例如,我经常在包含代码的 Beamer 演示文稿中使用 LaTeX 的 listings 包。

创建演示文稿

要创建一个 Beamer 文档,输入:

\documentclass{beamer}

与任何其他 LaTeX 文档一样,添加你要使用的任何包。例如,要使用 listings 包,请输入:

\usepackage{listings}

将所有内容放在 document 环境中:

\begin{document}

Beamer 文档通常时是一系列的 frame 环境。包含代码的 frame 应该被标记为 fragile

\begin{frame}[fragile]

使用标题开始你的 frame

\frametitle{Function to Do Stuff}

开始演示前测试你的代码

世上最糟糕的感受之一你在演讲中说到代码时,突然发现了一个 bug —— 也许是拼错了关键词或者漏掉了括号。

解决方法之一就是测试演示的代码。在多数演示环境中,这意味着创建一个单独的文件、编写测试接着拷贝和粘贴。

然而,在 Beamer 中有一种更好的方法。想象一下,你有一个名为 do_stuff.py 的文件,其中包含代码。你可以在第二个文件中编写 do_stuff.py 代码的测试,你可以将其命名为 test_do_stuff.py,并且可以使用 pytest 测试。但是,do_stuff.py 中的大多数行都缺乏教学价值,比如定义辅助函数。

要简化你受众看到的东西,你可在演示文稿中只导入你要讨论的行到 frame 中:

\lstinputlisting[
    language=Python,
    firstline=8,
    lastline=15
]{do_stuff.py}

由于你会对这几行(从 8 到 15)进行讨论,因此幻灯片上不需要任何其他内容。结束 frame

\end{frame}

在下一张幻灯片中,你想展示刚才的 do_stuff() 函数的用法示例:

\begin{frame}[fragile]
\frametitle{Calling Function to Do Stuff}
\lstinputlisting[
    language=Python,
    firstline=17,
    lastline=19
]{do_stuff.py}
\end{frame}

你使用相同的文件,但这次显示调用该函数的行。最后,结束 document

\end{document}

假设你在 do_stuff.py 中有一个合适的 Python 文件,这将生成一个含有 2 页的幻灯片。

Beamer 还支持必要的功能如渐进式演示,每次给观众展示一部分以免受到前面的打扰。在行中放入 \pause 会将页面分成不同的部分:

\begin{frame}
Remember:
\begin{itemize}
\item This will show up on the first slide. \pause
\item This will show up on the
      second slide, as well as the preceding point. \pause
\item Finally, on the third slide,
       all three bullets will show up.
\end{frame}

创建讲义

Beamer 中我最喜欢的功能是可以用 \documentclass[ignorenonframetext]{beamer} 设置忽略 frame 外的所有内容。当我准备演示文稿时,我离开顶部(声明文档类的位置)并自动生成它的两个版本:我的演示稿使用 Beamer 忽略任何 frame 之外的所有文本,另一个含有类似这样的头:

\documentclass{article}
\usepackage{beamerarticle}

这会生成一份讲义:一份含有所有 frame 和它们之间文字的 PDF。

当会议组织者要求我发布我的幻灯片时,我会包含原始幻灯片作为参考,但我希望人们拿到的是讲义,它包含了所有我不想在幻灯片上写的解释部分。

在创建幻灯片时,人们经常会考虑是为演讲优化讲稿还是为之后想要阅读它的人们优化。幸运的是,Beamer 提供了两全其美的办法。


via: https://opensource.com/article/19/1/create-presentations-beamer

作者:Moshe Zadka 选题:lujun9972 译者:geekpi 校对:wxy

本文由 LCTT 原创编译,Linux中国 荣誉推出

如何表达你的感激之情。

每天,我使用的那些高质量的软件 —— 开发和维护这些软件的人不需要我为之付款,他们尊重我的自由,并且慷慨地付出时间和精力。

在这个感恩的季节,我鼓励那些也使用和欣赏开源和自由软件维护者工作的人表达你的感激之情。以下是十种方法:

容易做到的

1、发送电子邮件感谢开发人员。具体点说,告诉他们你使用他们的什么软件以及它是如何帮助了你。

2、使用你最喜爱的社交媒体平台宣传它。

3、写一篇关于你最喜欢的软件的博客文章。

捐款

4、如果你最喜欢的开源项目接受捐款,请汇款。

5、如果你受雇于使用开源软件的公司,看你是否可以说服管理层赞助某些项目。

6、尽你所能地捐款。社交动机能做的不可思议!

花费时间

7、帮助审查补丁。

8、帮助分类 bug。

9、回答 IRC、邮件列表或 Stack Overflow 中的问题。

10、额外的:如果你像我一样,你在某个时候对开源社区的其他人说了一些严厉的话。承诺做得更好:用善良和开放沟通。感谢的最好方式是让开源社区成为人们能舒适沟通的地方。


via: https://opensource.com/article/18/11/ways-give-thanks-open-source

作者:Moshe Zadka 选题:lujun9972 译者:geekpi 校对:wxy

本文由 LCTT 原创编译,Linux中国 荣誉推出

toolz 库允许你操作函数,使其更容易理解,更容易测试代码。

在这个由两部分组成的系列文章的第二部分中,我们将继续探索如何将函数式编程方法中的好想法引入到 Python中,以实现两全其美。

在上一篇文章中,我们介绍了不可变数据结构。 这些数据结构使得我们可以编写“纯”函数,或者说是没有副作用的函数,仅仅接受一些参数并返回结果,同时保持良好的性能。

在这篇文章中,我们使用 toolz 库来构建。 这个库具有操作此类函数的函数,并且它们在纯函数中表现得特别好。 在函数式编程世界中,它们通常被称为“高阶函数”,因为它们将函数作为参数,将函数作为结果返回。

让我们从这里开始:

def add_one_word(words, word):
    return words.set(words.get(word, 0) + 1)

这个函数假设它的第一个参数是一个不可变的类似字典的对象,它返回一个新的类似字典的在相关位置递增的对象:这就是一个简单的频率计数器。

但是,只有将它应用于单词流并做归纳时才有用。 我们可以使用内置模块 functools 中的归纳器。

functools.reduce(function, stream, initializer)

我们想要一个函数,应用于流,并且能能返回频率计数。

我们首先使用 toolz.curry 函数:

add_all_words = curry(functools.reduce, add_one_word)

使用此版本,我们需要提供初始化程序。但是,我们不能只将 pyrsistent.m 函数添加到 curry 函数中; 因为这个顺序是错误的。

add_all_words_flipped = flip(add_all_words)

flip 这个高阶函数返回一个调用原始函数的函数,并且翻转参数顺序。

get_all_words = add_all_words_flipped(pyrsistent.m())

我们利用 flip 自动调整其参数的特性给它一个初始值:一个空字典。

现在我们可以执行 get_all_words(word_stream) 这个函数来获取频率字典。 但是,我们如何获得一个单词流呢? Python 文件是按行供流的。

def to_words(lines):
    for line in lines:
        yield from line.split()

在单独测试每个函数后,我们可以将它们组合在一起:

words_from_file = toolz.compose(get_all_words, to_words)

在这种情况下,组合只是使两个函数很容易阅读:首先将文件的行流应用于 to_words,然后将 get_all_words 应用于 to_words 的结果。 但是文字上读起来似乎与代码执行相反。

当我们开始认真对待可组合性时,这很重要。有时可以将代码编写为一个单元序列,单独测试每个单元,最后将它们全部组合。如果有几个组合元素时,组合的顺序可能就很难理解。

toolz 库借用了 Unix 命令行的做法,并使用 pipe 作为执行相同操作的函数,但顺序相反。

words_from_file = toolz.pipe(to_words, get_all_words)

现在读起来更直观了:将输入传递到 to_words,并将结果传递给 get_all_words。 在命令行上,等效写法如下所示:

$ cat files | to_words | get_all_words

toolz 库允许我们操作函数,切片、分割和组合,以使我们的代码更容易理解和测试。


via: https://opensource.com/article/18/10/functional-programming-python-toolz

作者:Moshe Zadka 选题:lujun9972 译者:Flowsnow 校对:wxy

本文由 LCTT 原创编译,Linux中国 荣誉推出

不可变性可以帮助我们更好地理解我们的代码。下面我将讲述如何在不牺牲性能的条件下来实现它。

在这个由两篇文章构成的系列中,我将讨论如何将函数式编程方法论中的思想引入至 Python 中,来充分发挥这两个领域的优势。

本文(也就是第一篇文章)中,我们将探讨不可变数据结构的优势。第二部分会探讨如何在 toolz 库的帮助下,用 Python 实现高层次的函数式编程理念。

为什么要用函数式编程?因为变化的东西更难推理。如果你已经确信变化会带来麻烦,那很棒。如果你还没有被说服,在文章结束时,你会明白这一点的。

我们从思考正方形和矩形开始。如果我们抛开实现细节,单从接口的角度考虑,正方形是矩形的子类吗?

子类的定义基于里氏替换原则。一个子类必须能够完成超类所做的一切。

如何为矩形定义接口?

from zope.interface import Interface

class IRectangle(Interface):
    def get_length(self):
        """正方形能做到"""
    def get_width(self):
        """正方形能做到"""
    def set_dimensions(self, length, width):
        """啊哦"""

如果我们这么定义,那正方形就不能成为矩形的子类:如果长度和宽度不等,它就无法对 set_dimensions 方法做出响应。

另一种方法,是选择将矩形做成不可变对象。

class IRectangle(Interface):
    def get_length(self):
        """正方形能做到"""
    def get_width(self):
        """正方形能做到"""
    def with_dimensions(self, length, width):
        """返回一个新矩形"""

现在,我们可以将正方形视为矩形了。在调用 with_dimensions 时,它可以返回一个新的矩形(它不一定是个正方形),但它本身并没有变,依然是一个正方形。

这似乎像是个学术问题 —— 直到我们认为正方形和矩形可以在某种意义上看做一个容器的侧面。在理解了这个例子以后,我们会处理更传统的容器,以解决更现实的案例。比如,考虑一下随机存取数组。

我们现在有 ISquareIRectangle,而且 ISequereIRectangle 的子类。

我们希望把矩形放进随机存取数组中:

class IArrayOfRectangles(Interface):
    def get_element(self, i):
        """返回一个矩形"""
    def set_element(self, i, rectangle):
        """'rectangle' 可以是任意 IRectangle 对象"""

我们同样希望把正方形放进随机存取数组:

class IArrayOfSquare(Interface):
    def get_element(self, i):
        """返回一个正方形"""
    def set_element(self, i, square):
        """'square' 可以是任意 ISquare 对象"""

尽管 ISquareIRectangle 的子集,但没有任何一个数组可以同时实现 IArrayOfSquareIArrayOfRectangle.

为什么不能呢?假设 bucket 实现了这两个类的功能。

>>> rectangle = make_rectangle(3, 4)
>>> bucket.set_element(0, rectangle) # 这是 IArrayOfRectangle 中的合法操作
>>> thing = bucket.get_element(0) # IArrayOfSquare 要求 thing 必须是一个正方形
>>> assert thing.height == thing.width
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
AssertionError

无法同时实现这两类功能,意味着这两个类无法构成继承关系,即使 ISquareIRectangle 的子类。问题来自 set_element 方法:如果我们实现一个只读的数组,那 IArrayOfSquare 就可以是 IArrayOfRectangle 的子类了。

在可变的 IRectangle 和可变的 IArrayOf* 接口中,可变性都会使得对类型和子类的思考变得更加困难 —— 放弃变换的能力,意味着我们的直觉所希望的类型间关系能够成立了。

可变性还会带来作用域方面的影响。当一个共享对象被两个地方的代码改变时,这种问题就会发生。一个经典的例子是两个线程同时改变一个共享变量。不过在单线程程序中,即使在两个相距很远的地方共享一个变量,也是一件简单的事情。从 Python 语言的角度来思考,大多数对象都可以从很多位置来访问:比如在模块全局变量,或在一个堆栈跟踪中,或者以类属性来访问。

如果我们无法对共享做出约束,那我们可能要考虑对可变性来进行约束了。

这是一个不可变的矩形,它利用了 attr 库:

@attr.s(frozen=True)
class Rectange(object):
    length = attr.ib()
    width = attr.ib()
    @classmethod
    def with_dimensions(cls, length, width):
        return cls(length, width)

这是一个正方形:

@attr.s(frozen=True)
class Square(object):
    side = attr.ib()
    @classmethod
    def with_dimensions(cls, length, width):
        return Rectangle(length, width)

使用 frozen 参数,我们可以轻易地使 attrs 创建的类成为不可变类型。正确实现 __setitem__ 方法的工作都交给别人完成了,对我们是不可见的。

修改对象仍然很容易;但是我们不可能改变它的本质。

too_long = Rectangle(100, 4)
reasonable = attr.evolve(too_long, length=10)

Pyrsistent 能让我们拥有不可变的容器。

# 由整数构成的向量
a = pyrsistent.v(1, 2, 3)
# 并非由整数构成的向量
b = a.set(1, "hello")

尽管 b 不是一个由整数构成的向量,但没有什么能够改变 a 只由整数构成的性质。

如果 a 有一百万个元素呢?b 会将其中的 999999 个元素复制一遍吗?Pyrsistent 具有“大 O”性能保证:所有操作的时间复杂度都是 O(log n). 它还带有一个可选的 C 语言扩展,以在“大 O”性能之上进行提升。

修改嵌套对象时,会涉及到“变换器”的概念:

blog = pyrsistent.m(
    title="My blog",
    links=pyrsistent.v("github", "twitter"),
    posts=pyrsistent.v(
        pyrsistent.m(title="no updates",
                     content="I'm busy"),
        pyrsistent.m(title="still no updates",
                     content="still busy")))
new_blog = blog.transform(["posts", 1, "content"],
                          "pretty busy")

new_blog 现在将是如下对象的不可变等价物:

{'links': ['github', 'twitter'],
 'posts': [{'content': "I'm busy",
            'title': 'no updates'},
           {'content': 'pretty busy',
            'title': 'still no updates'}],
 'title': 'My blog'}

不过 blog 依然不变。这意味着任何拥有旧对象引用的人都没有受到影响:转换只会有局部效果。

当共享行为猖獗时,这会很有用。例如,函数的默认参数:

def silly_sum(a, b, extra=v(1, 2)):
    extra = extra.extend([a, b])
    return sum(extra)

在本文中,我们了解了为什么不可变性有助于我们来思考我们的代码,以及如何在不带来过大性能负担的条件下实现它。下一篇,我们将学习如何借助不可变对象来实现强大的程序结构。


via: https://opensource.com/article/18/10/functional-programming-python-immutable-data-structures

作者:Moshe Zadka 选题:lujun9972 译者:StdioA 校对:wxy

本文由 LCTT 原创编译,Linux中国 荣誉推出