文档规范

使用sphinx

http://openalea.gforge.inria.fr/doc/openalea/doc/_build/html/source/sphinx/rest_syntax.html

使用Sphinx解析markdown

This is my answer, taken from StackOverflow

You can use Markdown and reStructuredText in the same Sphinx project. How to do this is succinctly documented on Read The Docs. Install recommonmark (pip install recommonmark) and then edit conf.py:

from recommonmark.parser import CommonMarkParser

source_parsers = {
    '.md': CommonMarkParser,
}

source_suffix = ['.rst', '.md']

markdown 内嵌rst

class recommonmark.transform.AutoStructify(*args, **kwargs)[source]

Bases: docutils.transforms.Transform

Automatically try to transform blocks to sphinx directives.

This class is designed to handle AST generated by CommonMarkParser.

实现方法

import recommonmark.transform
github_doc_root = 'https://github.com/rtfd/recommonmark/tree/master/doc/'
def setup(app):
    app.add_config_value('recommonmark_config', {
            'url_resolver': lambda url: github_doc_root + url,
            'auto_toc_tree_section': 'Contents',
            }, True)
    app.add_transform(recommonmark.transform.AutoStructify)

### ```eval_rst
### .. autoclass:: recommonmark.transform.AutoStructify
###    :show-inheritance:
### ```

还可以引用其他文档

一个高级例子

Line numbers and highlights

emphasis-lines:
highlights the lines.
linenos:
shows the line numbers as well.
caption:
shown at the top of the code block.
name:
may be referenced with :ref: later.
An example code-block with everything turned on.
1
2
3
4
5
# Comment line
import System
System.run_emphasis_line
# Long lines in code blocks create a auto horizontal scrollbar
System.exit!

rst, reST, reStructuredText, reST, standard reST markup

语法手册

https://zh-sphinx-doc.readthedocs.io/en/latest/rest.html

English Version

http://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html

学习手册

https://my-study-restructuredtext.readthedocs.io/en/latest/
http://openalea.gforge.inria.fr/doc/openalea/doc/_build/html/source/sphinx/rest_syntax.html

sphinx-quickstart

doc/content.rst 
sphinx-build docs/ docs/build
http://www.sphinx-doc.org/en/stable/usage/quickstart.html

sphinx.ext.autodoc

https://www.sphinx-doc.org/en/master/usage/extensions/autodoc.html

发布与安装

打包

历史:

distutils, setuptools, distribute, distutils, distlib

推荐:

pbr, https://pypi.org/project/pbr/

wheel

像jar包一样使用wheel包

# package a wheel
python setup.py bdist_wheel

# run cmd line from wheel
python wheel-0.21.xxx.whl/wheel -h 

# another example
python foobar.zip
# eq
PYTHONPATH=foobar.zip python -m __main__

# another example
python foobar.zip/mymod
PYTHONPATH=foobar.zip python -m mymod.__main__

制作安装包

python setup.py bdist_wheel upload -r testpypi

install

easy_install, Egg 缺少删除功能

实用pip

piphttps://pip.readthedocs.io/en/stable/user_guide


# installpi
pip install numpy --timeout 60
pip install -i https://testpypi.python.org/pypi ceilometer

列出当前安装包

pip freeze

发布

setup.py sdist
python setup.py register -r testpypi
python setup.py sdist upload -r testpypi

入口点和插件

ep

Entry points are a simple way for distributions to “advertise” Python objects (such as functions or classes) for use by other distributions.

entry_point_inspector: 查看入口点信息

通入规范的放口点描述，找到符合条件的模块函数
epi group list
epi group show gui_scripts
epi ep show gui_scripts spyder

pkg_resources发现和加载入口点信息

建立插件机制

入口点机制提供了巨大的可能性，可以用来构建驱动系统，钩子系统以及简单而通用的扩展。

stevedore

stevedore

Python makes loading code dynamically easy, allowing you to configure and extend your application by discovering and loading extensions (“plugins”) at runtime. Many applications implement their own library for doing this, using import or importlib. stevedore avoids creating yet another extension mechanism by building on top of setuptools entry points. The code for managing entry points tends to be repetitive, though, so stevedore provides manager classes for implementing common patterns for using dynamically loaded extensions.

一个例子

学习Python动态扩展包stevedore

http://yansu.org/2013/06/09/learn-python-stevedore-module-in-detail.html

开发环境与工具

reference

https://github.com/jobbole/awesome-python-cn

虚拟环境

virtual env

virtualenv venv --system-site-package

pip

config windows: C:\Users\tony\AppData\Roaming\pip\pip.ini

[global]
timeout = 60
index-url = https://pypi.tuna.tsinghua.edu.cn/simple

trusted-host = pypi.python.org
               pypi.org
               files.pythonhosted.org
               pypi.tuna.tsinghua.edu.cn

vscode

config for windows

{
    "cmake-tools-helper.cmake_download_path": "c:\\Users\\tony\\.vscode\\extensions\\maddouri.cmake-tools-helper-0.2.1\\cmake_download",
    "workbench.startupEditor": "newUntitledFile",
    "workbench.colorTheme": "Electron Highlighter",
    "terminal.integrated.shell.windows": "C:\\WINDOWS\\System32\\cmd.exe",
    "terminal.integrated.shellArgs.windows" : ["/K", "C:\\Users\\tony\\Anaconda3\\Scripts\\activate.bat", "C:\\Users\\tony\\Anaconda3"],
    "git.enableSmartCommit": true,
    "git.autofetch": true,
    "editor.suggestSelection": "first",
    "vsintellicode.modify.editor.suggestSelection": "automaticallyOverrodeDefaultValue",
    "python.jediEnabled": false
}

config for linux

linux path: /home/tony/.pip/pip.conf

[global]
index-url = http://mirrors.aliyun.com/pypi/simple/

[install]
trusted-host=mirrors.aliyun.com

lint

print

from pprint import pprint

test

unit test

test_打头的文件和函数

nosetests

tox

ci

TODO 工作流

gerrit：代码审查 Jenkins：CI Travis：代码的签入后运行测试 Zuul: 工作流 Sonar：质量检查和展示

profile

examples.profile.use_cprofile.note()[source]

python -m cProfile -s time myscript.py

显示工具KCacheGrind，显示Valgrind的输出

pyprof2calltree将cProfile的输出转化成Valgrind的格式， -o选项

使用pypy，代替CPython

python -m memory_profiler script.py

memory_profiler

using memoryview

time.perf_counter()

timeit

profile

examples.profile.use_cprofile.x()[source]
>>> dis.dis(x)
dis模块对python代码反编译

API变化

sphinx标记

    .. deprecated:: 1.1

warnings 模块，warnings.warn()

    warnings.warn("turn_left is deprecated sin Version 1.1, use trun instead")

debtcollector模块标注

    from debtcollector import moves
    @move.moved_method("turn",version="1.1")

语法

class examples.lang.slots.Point(x, y)[source]

Bases: object

x
y
examples.lang.slots.use_namedtuple()[source]

collections.namedtuple(“Foobar”, [“x”, “y”])

class examples.lang.api.UseDebtcollector[source]

Bases: object

https://docs.openstack.org/debtcollector/latest/user/index.html

A collection of Python deprecation patterns and strategies that help you collect your technical debt in a non-destructive manner. The goal of this library is to provide well documented developer facing deprecation patterns that start of with a basic set and can expand into a larger set of patterns as time goes on. The desired output of these patterns is to apply the warnings module to emit DeprecationWarning or PendingDeprecationWarning or similar derivative to developers using libraries (or potentially applications) about future deprecations.

trun(direction='left')[source]
trun_left()[source]

Deprecated since version 1.1.

inspect

inspect - Get useful information from live Python objects.

functools

ABCMeta

six模块是Python为了兼容Python 2.x 和Python 3.x提供的一个模块，该模块中有一个针对类的装饰器 @six.add_metaclass(MetaClass) 可以为两个版本的Python类方便地添加metaclass。这样我们就可以同时利用Python中的abc模块和six模块在类的定义前添加 @six.add_metaclass(abc.ABCMeta) 来优雅地声明一个抽象基础类了！

    import six
    import abc

    @six.add_metaclass(abc.ABCMeta)
    class PluginBase(object) :
        pass

super(), mro()

mro method resolution order

util

print

num = 1
print(f"coroutine_{num} start")

import

examples.lang.import.import_module()[source]

import module from module file

examples.lang.import.import_source()[source]

import from source file

function

examples.lang.fun.func(a: int, b: dict) → set[source]

function with annotation

语法(asyncio)

functional programming

generator

inspect.isgeneratrofunction() inspect.getgeneratorstate()

genexpr

l = [1,2,3,4]
g = (i for i in l)

list comprehension, listcomp

[ str(i) for i in [1,2,4]]
{ x:x.upper() for x in ["hello", "world"]}
{ x.upper() for x in ["hello", "world"]}

built-in

map(func, iterable)
filter(func or None, iterable)
enumerate(iterable[,start])
sorted(iterable, key=None, reverse=False)
any(iterable)
all(iterable)
zip(iter1[,iter2])

libs

first

from first import first
first([-1,0,1,2], key=lambda x: x>0)

def greater_than_zero(n):
    return n > 0

first(iterable, key = greater_than_zero)

functools

[‘RLock’, ‘WRAPPER_ASSIGNMENTS’, ‘WRAPPER_UPDATES’, ‘cmp_to_key’, ‘get_cache_token’, ‘lru_cache’, ‘namedtuple’, ‘partial’, ‘partialmethod’, ‘recursive_repr’, ‘reduce’, ‘singledispatch’, ‘total_ordering’, ‘update_wrapper’, ‘wraps’]

import functools
from first import first

def greater_than(number, min=0):
    return number > min

first(iterable, key = functools.partial(greater_than, min = 42))

operator

[‘abs’, ‘add’, ‘and_’, ‘attrgetter’, ‘concat’, ‘contains’, ‘countOf’, ‘delitem’, ‘eq’, ‘floordiv’, ‘ge’, ‘getitem’, ‘gt’, ‘iadd’, ‘iand’, ‘iconcat’, ‘ifloordiv’, ‘ilshift’, ‘imatmul’, ‘imod’, ‘imul’, ‘index’, ‘indexOf’, ‘inv’, ‘invert’, ‘ior’, ‘ipow’, ‘irshift’, ‘is_’, ‘is_not’, ‘isub’, ‘itemgetter’, ‘itruediv’, ‘ixor’, ‘le’, ‘length_hint’, ‘lshift’, ‘lt’, ‘matmul’, ‘methodcaller’, ‘mod’, ‘mul’, ‘ne’, ‘neg’, ‘not_’, ‘or_’, ‘pos’, ‘pow’, ‘rshift’, ‘setitem’, ‘sub’, ‘truediv’, ‘truth’, ‘xor’]

import operator
import functools import partial
import first
frist(iterable, key = partial(operator.le, 0))

itertools

[‘accumulate’, ‘chain’, ‘combinations’, ‘combinations_with_replacement’, ‘compress’, ‘count’, ‘cycle’, ‘dropwhile’, ‘filterfalse’, ‘groupby’, ‘islice’, ‘permutations’, ‘product’, ‘repeat’, ‘starmap’, ‘takewhile’, ‘tee’, ‘zip_longest’]

算法

examples.algorithm.use_collection()[source]
set
add,clear,copy,difference,difference_update,discard,intersection, intersection_update,isdisjoint,issubset,issuperset,pop,remove, symmetric_difference,symmetric_difference_update,union,update
dict
clear,copy,fromkeys,get,items,keys,pop,popitem,setdefault,update,values
list
append,clear,copy,count,extend,index,insert,pop,remove,reverse,sort
tuple
count,index
examples.algorithm.use_bisect.use_bisect()[source]
bisect
二分查找
blist，bintree
二叉树和红黑树
examples.algorithm.use_defaultdict.add_animal_in_family(species, animal, family)[source]

collections.defaultdict

examples.algorithm.memoization.memoized_sin[source]

functools.lru_cache(maxsize)

开发库支持

stdlib

os

import os
# Determine path to this module
OPENSHOT_PATH = os.path.dirname(os.path.realpath(__file__))

datetime

datetime, pytz, ios8601

extern lib

选用标准：python兼容，开发活跃，维护活跃，与发行版打包，API向后兼容，版权

gui-lib

framework

gevent

examples.libs.use_gevent.asyncfun()[source]

start a group async task

examples.libs.use_gevent.joinall()[source]
examples.libs.use_gevent.use_Actor()[source]

Actor: a higher level concurrency model popularized by the language Erlang

examples.libs.use_gevent.use_Greenlet()[source]

Greenlet : thread

examples.libs.use_gevent.use_zmq()[source]

gevent-zmq

math

math

net

net

frameworks

framework

开发库支持(frameworks)

RxPy

examples.frm.rxpy.userx()[source]

document https://rxpy.readthedocs.io/en/latest/

reactive programming in python: https://auth0.com/blog/reactive-programming-in-python/

ReactiveX : http://reactivex.io/

observable, observer/subscribe, subject

data stream

toolbox = filter, create, transform, unify

event-driven programming: handling any event to trigger the corresponding action

reactive: wrap data into the reactive system as events

开发库支持(Qt)

Qt.py

快捷键管理

设置全局快捷键 https://github.com/codito/pyqtkeybind

gevent

qconsole

class examples.libs.qt.iconsole.MainWindow[source]

Bases: PyQt5.QtWidgets.QMainWindow

A window that contains a single Qt console.

shutdown_kernel()[source]
examples.libs.qt.iconsole.make_jupyter_widget_with_kernel()[source]

Start a kernel, connect to it, and create a RichJupyterWidget to use it

examples.libs.qt.inprocess.show()[source]

An example of embedding a RichJupyterWidget with an in-process kernel. We recommend using a kernel in a separate process as the normal option - see embed_qtconsole.py for more information. In-process kernels are not well supported. To run this example:

python3 inprocess_qtconsole.py

开发库支持(math)

numpy

multiprocessing

开发库支持(net.Scrapy)

Scrapy shell

testing XPath or CSS expressions

scrapy.cfg:

[settings]
shell = bpython

中断，并进入到调试模式

from scrapy.shell import inspect_response
inspect_response(response, self)

调试插件 https://docs.scrapy.org/en/latest/topics/extensions.html#debugger-extension

class scrapy.extensions.debug.Debugger
Invokes a Python debugger inside a running Scrapy process when a SIGUSR2 signal is received. After the debugger is exited, the Scrapy process continues running normally.

Other

ScreenShot

Splash - A javascript rendering service Splash is a javascript rendering service. It’s a lightweight web browser with an HTTP API, implemented in Python 3 using Twisted and QT5. The (twisted) QT reactor is used to make the service fully asynchronous allowing to take advantage of webkit concurrency via QT main loop.

存储

ORM RMDB NoSQL

Neo4j

中文文档 http://neo4j.com.cn/public/docs/index.html

sqlite

社区

  • Full Stack Python

    https://www.fullstackpython.com/

  • Nodeclub

    使用 Node.js 和 MongoDB 开发的社区系统 http://cnodejs.org/ https://github.com/cnodejs/nodeclub/

  • Neo4j

    http://neo4j.com.cn/

TODOS

rST文档样式

参考:

https://github.com/zhaojiedi1992/My_Study_ReStructuredText

标题:

================
目标样式
================

二级标题是这样的
================

----------------
三级标题是这样的
----------------

四级标题是这样的
----------------

`````````
五级标题
`````````

六级标题
`````````

Indices and tables