Principles of Programming Cheatsheet

Part 1 Packages, Modules and Installable+Editable Mode

如何写一个Python Package并且让它能被下载，并且Editable？

我们首先需要文件结构如下：


-- your_package
	 -- __init__.py
	 -- your_module.py
-- setup.py

在setup.py中我们需要有以下代码让python的setuptools找到你的package，记得将修改your-package-name修改成你自己规定的名字：


from setuptools import setup, find_packages
setup(
    name="your-package-name",
    version="0.1",
    packages=find_packages(),
)

最后我们需要安装这个package (in editable mode), 我们需要进入包含这个package的文件夹，然后在命令行中输入 (请勿忽略最后的.！！！)：


python -m pip install -e .

如果命令行提示安装成功，则可进入下一步进行coding exercises.

Part 2 Object-Oriented Programming in Python - 面向对象编程

2.1 面向对象简介

如何写一个 Class?

假设我们需要写一个 Class 叫做 Foo （没错，类的名称首字母必须大写， 并且遵循驼峰命名法，即组成类名称的每一个单词的首字母必须大写，例如MyUniqueClass）, 我们将会有以下的代码:


class Foo:
    # some methods in the class

如何写一个 Class 的 constructor？

当你在题目中看到constructor 这个词之后，你应该意识到题目正在对于class中__init__ 方法进行说明，我们将会有以下的代码：


class Foo:
    def __init__(self, argument1, argument2, ...):
        self.attribute1 = argument1
        self.attribute2 = argument2
				...

特别地，__init__ 方法的作用是将外界传入的参数值储存到类的属性 (attribute) 中，如上方代码中的self.attribute1。同时，未来在其他类内方法中调用类的属性值的时候我们只能使用self.attribute1 进行引用，而不能使用传入constructor的argument1 进行引用。

如何写一个 Class 的 subclass ？

假设我们需要构造Foo的子类 Bar ，我们将会有以下代码：


class Bar(Foo):
    # some methods in the subclass

其中Bar(Foo) 表示如果不对于Bar类内的方法进行修改，Bar 类将继承Foo 类的全部属性以及方法。

如何写一个 Class 内部的方法？

代码如下（在写方法时我们不可以忽略函数参数中的self）：


class Foo:
    def __init__(self, argument1, argument2, ...):
        self.attribute1 = argument1
        self.attribute2 = argument2
				...
		# some methods in the class
		def set_attribute1(self, new_argument_1):
        self.attribute1 = new_argument_1
		# more methods in the class

特别地，当我们在调用函数set_attribute1 的时候，函数的参数中将不含有self 关键字，例如对于一个Foo类的实例（instance）f, 我们可以调用 f.set_attribute1(new_argument_1 = 1) 这个方法 (method)。同时在本例中参数名new_argument_1 在实际调用中也可以不加，在这里只是起到指示作用。

如何获取一个 Class 的名字？

这串代码通常用于类的 __str__ 或 __repr__ 方法中：


type(self).__name__

代码中的self 关键字也可以换成任意对象的实例（instance）。

2.2 字符串相关

如何优雅的打印/返回具有格式的字符串？

假设我们有以下变量 first, second = 1, 4 ，我们同时希望打印出一串字符串显示第一个元素（变量）以及第二个元素的值，我们当然可以用一行代码将这个字符串进行打印：


print("The first element is " + str(first) + ", and the second is " + str(second) + ".")

但这种方式虽然直观，却在编码（coding）过程中需要考虑字符之间是否需要存在空格，如第一个字符串“The first element is”之后必须添加一个空格，然后再与str(first) 进行合并，或是标点符号之后必须存在空格。

我们可以使用f"" 以及{} 对于字符串进行”格式化”，以一种更加优雅的形式对于字符串进行打印。以下是一个简单的例子：


>>> first, second = 1, 4
>>> print(f"The first element is {first}, and the second is {second}.")

打印的结果将会是：


The first element is 1, and the second is 4.

通俗一些的解释是 f”” 指代这个字符串将要被“格式化”，同时 {} 内部将填入 “格式” 内所对应的变量的值（即字符串中的{first}直接被替换成变量first 的值 1 ）。

如何用特定的分隔符连接一个序列的元素？

我们将使用join() 方法来连接元素。假设我需要用", " 连接列表[1, 4, 2, 8, 5, 7] 中的元素并输出一个不包含方括号”[”, ”]”的字符串，应该使用以下的代码：


>>> number_list = [1, 4, 2, 8, 5, 7]
>>> print(", ".join([str(num) for num in number_list]))

输出的字符串将会是：


“1, 4, 2, 8, 5, 7”

即我们只要将序列中的元素转换成 string 类型，也就是创造一个新的包含所有原序列中所有元素字符串形式的新序列，再如上方代码样例所示使用 join() 方法即可将所有元素通过特定的分隔符连接。

注意：

join() 方法只能应用在以字符串为元素的序列上！！！

思考一下：虽然我们已经知道对于基本的数据类型，例如整数，它的字符串形式就是它本身加上周围的单/双引号构成的字符串。但对于一些复杂的数据类型，比如一个自定义的类，它也是如此吗？如果不是，我们该怎么按照特定的需求实现数据类型和相应字符串之间的转换？

如何写一个`str`方法？

实现一个类的__str__ 能够使得这个类在被调用print()打印，或使用str()方法返回对应字符串的时候不只是返回该实例所在的地址，在没有实现__str__ 方法的情况下，我们会得到例如下方控制台 (terminal) 中代码显示的字符串：


> python3
Python 3.9.12 (main, Mar 26 2022, 15:51:15) 
[Clang 13.1.6 (clang-1316.0.21.2)] on darwin
Type "help", "copyright", "credits" or "license" for more information.
>>> f = Foo()
>>> str(f)
>>> '<__main__.Foo object at 0x101e5b730>'
>>> print(f)
>>> '<__main__.Foo object at 0x101e5b730>'

同时包含一些关于这个class instance的有效信息，例如属性值（attribute value）。为了实现这个方法，我们只需要如下的代码即可, 例如我希望__str__ 方法能够返回形如Foo(a=attribute1, b=attribute2) 的一个字符串，我们可以这么实现这个方法：


class Foo:
    # Constructor and the other methods.
    def __str__(self):
        return f"{type(self).__name__}(a={self.attribute1}, b={self.attribute2})"

在实现该方法之后我们就可以使用print()打印Foo类实例的信息或用str()返回代表Foo类实例信息的一个字符串了，控制台 (terminal)中的代码如下：


> python3
Python 3.9.12 (main, Mar 26 2022, 15:51:15) 
[Clang 13.1.6 (clang-1316.0.21.2)] on darwin
Type "help", "copyright", "credits" or "license" for more information.
>>> f = Foo(1, 2)
>>> print(f)
Foo(a=1, b=2)
>>> str(f)
Foo(a=1, b=2)

这进一步说明了，在使用print(f) 打印信息的时候，python首先隐性地调用了str(f) 返回 f 所对应的字符串，然后再将该字符串使用print打印出来，即实际python解释器对于print(f)的操作为print(str(f))。由于每一个类的__str__()方法by default会返回该对象实例的地址，这就说明了为什么我们在没有对一个对象显性地实现__str__()的时候，print()会打印形如'<__main__.Foo object at 0x101e5b730>' 的字符串。

如何写一个`repr`方法?

实现一个类的__repr__ 能够使得这个自定义类在控制台中尝试通过输入变量名+回车的方式显示信息的时候，不只是返回该实例所在的地址（看到这里你可能觉得有一些困惑，希望下面的控制台代码例子能够帮到你）。在没有实现__repr__ 方法的情况下，我们会得到例如下方控制台 (terminal) 中代码显示的字符串：


> python3
Python 3.9.12 (main, Mar 26 2022, 15:51:15) 
[Clang 13.1.6 (clang-1316.0.21.2)] on darwin
Type "help", "copyright", "credits" or "license" for more information.
>>> f = Foo()
>>> f
>>> '<__main__.Foo object at 0x101e5b730>'

这同时说明了当我们在控制台中输入 f+回车 的时候（即上方代码倒数第二行），python将隐性的调用__repr__() 方法，同时有以下的输出:


>>> repr(f) # Interpreted by python as you enter variable f and 'enter' (回车)
>>> '<__main__.Foo object at 0x101e5b730>'

__repr__ 的写法与__str__类似（我个人的愚见是，只要仔细读清楚题目对于格式的要求即可，并不用拘泥与某一种特定的代码写法）。下面我将以一个Expr类作为例子：

对于一个Expr类的实例它可以有多个operand (显然，每个operand也一定是一个Expr类)，我们把这一系列的operand叫做operands .

在constructor中的*operands可以被浅显的理解为这个constructor允许输入多个位置参数，例如Expr(operand1, operand2) 。
同时，输入的所有参数将打包成一个tuple作为operands 这个变量的值，即operands = (operand1, operand2) 。
最后operands变量的值将会以tuple的形式储存在Expr的self.operands 属性中。


class Expr: 
    def __init__(self, *operands):
        self.operands = operands

对于 Expr 类的 __repr__ 方法，我们希望这个方法返回的字符串有以下几个要素：

该实例（instance）的 class name
该Expr实例的所有operand通过__repr__返回的信息字符串

每个字符串之间使用逗号+空格 (comma + space) 进行连接
使用括号 (brackets) 进行包裹上方连接后的字符串

接下来我将根据题目所提供的几个要素，对于这种题目的思路进行分析以及给出一种解法：

如何获取一个类实例的class name？（面向对象简介最后一个问题）


type(self).__name__

如何获取所有operand通过__repr__返回的信息字符串？

注意：题目中可能会提供一些细节信息，例如Expr类有以下几个子类（subclass），其中某几个子类的__repr__ 方法会有所不同 ... 目前不必考虑太多！！！你需要做的就是根据题意把最general的部分用代码写出来。如果你写出来了，相当于整个Expr类的大体框架已经搭好，你已经成功一大半了。接下来的工作才是对于细节进行一系列的补充，而不是从一开始就深入考虑细节。

接下来我会用一种较为优雅的写法来提供一种解法：


operands_repr = [repr(operand) for operand in self.operands]

当然，如果你不熟悉这种写法，下面这种方法也一定不会错：


operands_repr = []
for operand in self.operands:
    operands_repr.append(repr(operand))

如何将每个字符串之间使用逗号+空格 (comma + space) 进行连接？（字符串相关，第二个问题）


“, ”.join(operands_repr)

最后我们需要做的，就是将连接后的字符串用括号进行包裹，同时优雅地将所有元素拼接起来：


def __repr__(self):
    operands_repr = [repr(operand) for operand in self.operands]
    return f"{type(self).__name__}({', '.join(operands_repr)})"

恭喜你走到到这一步，我们的工作就算完成了。

内置类型转字符串中可能忽略的问题（建议阅读）

目前看似我们掌握了许多东西，但是有一些细节仍然需要注意。

你可能发现大多数python的内置类型 __str__ 和__repr__ 的返回值是相同的（例如int类型和bool类型），我们在控制台可以看到：


> python3
Python 3.9.12 (main, Mar 26 2022, 15:51:15) 
[Clang 13.1.6 (clang-1316.0.21.2)] on darwin
Type "help", "copyright", "credits" or "license" for more information.
>>> type(1)
<class 'int'>
>>> str(1) == repr(1)
True
>>> str(1)
'1'
>>> type(True)
<class 'bool'>
>>> str(True) == repr(True)
True
>>> str(True)
'True'

而且这些类型的__str__ 和 __repr__ 方法都返回一个使用单引号包裹变量值本身的字符串。

但是特别地，对于一个字符串来说这个规律并不适用，我们可以看到：


>>> type('HELLO')
<class 'str'>
>>> str('HELLO')
'HELLO'
>>> repr('HELLO')
"'HELLO'"

你可能会怀疑是不是我这里字符串使用的是单引号而不是双引号包裹引发的问题，但我很确切地知道不是这个问题（你也可以自己试试），这就是在python语言设计上的一个特性。

对于一个字符串，它的__str__ 方法将返回它本身，但它的__repr__ 方法将返回一个不同的字符串，这个返回的字符串用双引号包裹了原字符串本身（如果原字符串已经被双引号包裹，则返回的字符串内部会变成单引号包裹的原字符串）。

也就是说，当我们尝试打印或实现某些方法的时候，字符串的表现会略有不同：


> python3
Python 3.9.12 (main, Mar 26 2022, 15:51:15) 
[Clang 13.1.6 (clang-1316.0.21.2)] on darwin
Type "help", "copyright", "credits" or "license" for more information.
>>> print(f"The string I want to print out is {str('Hello')}.")
The string I want to print out is Hello.
>>> print(f"The string I want to print out is {repr('Hello')}.")
The string I want to print out is 'Hello'.

思考一下，如果我有一个class Symbol , 它的__repr__方法需要满足这个条件：假如我有一个instance x = Symbol('x'), 我希望它的__repr__方法能够返回 "Symbol('x')" , 即返回一个包含类型名称、括号以及类型属性值（满足上述要求）的字符串，你应该如何实现它呢？

希望上面的资料对于你思考这个问题有所帮助。

2.3 Special Method相关

如何写关于四则运算的特殊方法 (e.g. `add`, `sub`, `mul` etc.)?

一般结构（以__add__为例）, 如果只考虑同一类别下实例的相加:


class Foo:
    def __add__(self, other):
        if isinstance(other, Foo):
		        # do something, e.g.
            new_attribute1 = self.attribute1 + other.attribute1
            new_attribute2 = self.attribute2 + other.attribute2
            return Foo(new_attribte1, new_attribute2)
        else:
            return NotImplemented

如果该类别可以和其他的类进行四则运算（如Expr类和numbers.Number类相加），我们则需要增加如下判断：


from numbers import Number
class Expr:
    def __add__(self, other):
        if isinstance(other, Expr):
		        # do something
        elif isinstance(other, Number):
            # do other things to allow Expr + Number
        else:
            return NotImplemented

同时由于加号两边可以存在不同类型，我们必须考虑如Number + Expr的情况（即不同于默认情况下Expr在加号左边的情况），增加一个__radd__ 方法：


def __add__(self, other):
    if isinstance(other, Expr):
        # do something
    elif isinstance(other, Number):
        # do other things to allow Number + Expr
    else:
        return NotImplemented

如何写关于逻辑运算的特殊方法 (e.g. `and`, `or`, `invert` etc.)?

对于二元操作（例如 and 和 or），我们有如下的模板：


class Expr:
    def __and__(self, other):
        if isinstance(other, Expr):
           return And(self, other)
        else: 
           return NotImplemented

    def __or__(self, other):
        if isinstance(other, Expr):
           return Or(self, other)
        else: 
           return NotImplemented


class And(Expr):
    pass


class Or(Expr):
    pass

对于一元操作（not），方法的实现将会更加简单：


class Expr:
    def __invert__(self):
        return Not(self)

class Not(Expr):
    pass

如何写关于判断两个对象相等/大小的特殊方法 (e.g. `eq`, `lt` etc.)?

我们对判断相等有如下的模板：


class Foo:
    def __eq__(self, other):
        return isinstance(other, Foo) \
               and self.attribute1 == other.attribute1 \
               and self.attribute2 == other.attribute2

对于判断大小，我们则需要注意题目中对于如何比较大小的要求，具体的方法模版如下：


class Foo:
    def __lt__(self, other):
        if isinstance(other, Foo):
		        # compare two objects as question said
        else:
		        return NotImplemented

2.4 数据结构相关

什么是序列 (Sequence)？每种序列都有什么对应的特殊方法？

Sequence，即一系列元素的集合。Python中许多东西都是序列，例如 tuple, list, set, queue 以及dictionary. 以下是本课中重点提及的序列的常用方法：

Tuple 类

声明一个tuple变量


my_tuple = (1, 2)

合并两个tuple


this_tuple = (1, 4)
other_tuple = (2, 8, 5, 7)
new_tuple = this_tuple + other_tuple # new_tuple should be (1, 4, 2, 8, 5, 7)

List （Python里面也可以认为是 Stack）

情境	方法	返回值？
创建一个空List/Stack	new_list = []	N/A
向列表中增加元素 a	new_list.append(a)	该方法不返回值，仅update new_list
移除列表尾部的元素	new_list.pop()	该方法返回移除的最后一个元素，同时update new_list

Queue （常用的队列为它的deque子类）

在练习以及考试中我们将会经常使用deque作为队列使用，特别地，与list不同，我们通常将deque的最右侧认作队首，而最左侧认作队尾。

情境	方法	返回值
创建一个空队列	new_queue = deque()	N/A
向队列尾部增加元素 a	new_queue.appendleft(a)	该方法不返回值，仅update new_queue
移除队列头部的元素	new_queue.pop()	该方法返回移除的元素，同时update new_queue

deque类也有append() 方法，该方法可以将一个元素a添加至队列的最前方，但是在考试中我们一般不使用它。

情境	方法	返回值
创建一个空集合	new_set = set()	N/A
向集合尾部增加元素 a	new_set.add(a)	该方法不返回值，仅update new_set
移除集合尾部的元素	new_set.pop()	该方法返回移除的元素，同时update new_set
向集合中增加多个元素	new_list.union(sub_list)	该方法返回new_list和sub_list的并集
获取两集合之间的交集	new_list.intersection(sub_list)	该方法返回new_list和sub_list的交集

2.5 Python进阶语法

Postvisitor + Single Dispatch

我们有以下的模版：


def postvisitor(expr, fn, **kwargs):
    '''Visit an Expression in postorder applying a function to every node.

    Parameters
    ----------
    expr: Expression
        The expression to be visited.
    fn: function(node, *o, **kwargs)
        A function to be applied at each node. The function should take
        the node to be visited as its first argument, and the results of
        visiting its operands as any further positional arguments. Any
        additional information that the visitor requires can be passed in
        as keyword arguments.
    **kwargs:
        Any additional keyword arguments to be passed to fn.
    '''
    return fn(expr,
              *(postvisitor(c, fn, **kwargs) for c in expr.operands),
              **kwargs)

假设我们将要 evaluate 一个Expr 类的值，我们会有以下方法实现Single Dispatch：

一个能够放进postvistor()的evaluate()函数：


from functools import singledispatch
import expressions


@singledispatch
def evaluate(expr, *o, **kwargs):
    """Evaluate an expression node.

    Parameters
    ----------
    expr: Expression
        The expression node to be evaluated.
    *o: numbers.Number
        The results of evaluating the operands of expr.
    **kwargs:
        Any keyword arguments required to evaluate specific types of
        expression.
    symbol_map: dict
        A dictionary mapping Symbol names to numerical values, for
        example:

        {'x': 1}
    """
    raise NotImplementedError(
        f"Cannot evaluate a {type(expr).__name__}")

注意：我们不可以忽略函数名称上方的@singledispatch 装饰器

以及各种dispatch functions：


@evaluate.register(Number)
def _(expr, *o, **kwargs):
    return expr.value


@evaluate.register(Symbol)
def _(expr, *o, symbol_map, **kwargs):
    return symbol_map[expr.value]


@evaluate.register(Add)
def _(expr, *o, **kwargs):
    return o[0] + o[1]


@evaluate.register(Sub)
def _(expr, *o, **kwargs):
    return o[0] - o[1]


@evaluate.register(Mul)
def _(expr, *o, **kwargs):
    return o[0] * o[1]


@evaluate.register(Div)
def _(expr, *o, **kwargs):
    return o[0] / o[1]


@evaluate.register(Pow)
def _(expr, *o, **kwargs):
    return o[0] ** o[1]

注意：dispatch functions的定义需要根据题目进行修改

希望本文对你有帮助。