Thanks to visit codestin.com
Credit goes to github.com

Skip to content

Commit 9eebf93

Browse files
huaxz1986huaxz1986
committed
add pip_usage, sphinx_usage,virtualenv_suage
1 parent 26f5862 commit 9eebf93

File tree

4 files changed

+311
-1
lines changed

4 files changed

+311
-1
lines changed

‎README.md

Lines changed: 29 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,2 +1,30 @@
11
# python_tools
2-
Python常用库以及第三方package的使用笔记
2+
<!--
3+
作者：华校专
4+
email: [email protected]
5+
** 本文档可用于个人学习目的，不得用于商业目的 **
6+
-->
7+
本项目中的笔记来自于个人在Python学习中使用的一些工具或者包的学习心得。
8+
## 缘由
9+
在使用Python第三方包过程中，我参考了网上的资料。但是发现各类资料、教程存在以下问题：
10+
11+
1. 运行结果不正确。这往往是版本不一致问题。也有少部分是转载过程中出现遗漏
12+
2. 只针对某部分特性进行介绍。这往往造成管中窥豹的后果，对该工具包的使用缺乏全局的眼光（比如该工具适用于哪些情形、哪些条件下会出问题、性能等）
13+
14+
因此我在使用这些第三方包的过程中参考它们自带的官方文档，记录下使用心得。
15+
16+
## 目标
17+
Python的第三方包数量庞大，质量参差不齐。我仅抽取了部分优秀的第三方包来介绍其使用
18+
19+
1. 所有的文档资料全部来源于第三方包自带的官方文档
20+
2. 大部分内容都经过真实的使用调试
21+
3. 本笔记跟随软件包的升级和更新其内容
22+
23+
>对于Python语法，请参考本人的另一个项目 https://github.com/huaxz1986/python_learning_notes
24+
25+
>本笔记采用Markdown格式编写，
26+
> 语法请参考本人的另一个项目 https://github.com/huaxz1986/markdown_documentation_chinese
27+
28+
**本文档仅用于个人学习目的，未经许可不得用于商业目的，转载请注明出处**
29+
30+
**email: [email protected]**

‎packages/pip_usage.markdown

Lines changed: 112 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,112 @@
1+
# pip使用指南
2+
3+
当你使用Python2.7.9以及Python3.4以上的Python版本时，pip已经默认随Python一起安装，但是你可能需要不定期的更新pip。
4+
5+
## 一、更新pip
6+
7+
* 在Linux或者OSX平台上执行命令 `pip install -U pip`
8+
* 在Windows平台上执行命令`python -m pip install -U pip`
9+
10+
## 二、使用pip
11+
12+
### 1.安装package
13+
#### a. 从PyPI安装
14+
15+
pip安装package最常见的就是从PyPI安装，从 [PyPI](http://pypi.python.org/pypi/) 安装package的命令为：
16+
17+
pip install SomePackage #安装最新的版本
18+
pip install SomePackage==1.0.4 #安装指定版本
19+
pip install 'SomePackage>=1.0.4' #minimum版本
20+
21+
>从PyPI用pip安装时，可能因为网络问题发生超时。此时可以指定国内镜像源，命令为：
22+
>`pip install SomePackage -i http://example.com`
23+
>常用的镜像源有：
24+
25+
>* 清华：http://mirrors.tuna.tsinghua.edu.cn/pypi/simple
26+
>* 豆瓣：http://pypi.douban.com/simple
27+
28+
>如果不希望每次运行pip命令时均手工添加，可以在配置文件中添加
29+
>
30+
> [global]
31+
> index-url=http://example.com
32+
>
33+
34+
#### b. 从Wheel安装
35+
Whell文件时一个打包的构建好的文件格式，比从源代码build然后install快得多。安装命令：
36+
37+
pip install SomePackage-1.0-py2.py3-none-any.whl
38+
39+
### c. 从本地源代码安装
40+
通常源代码中都有`setup.py`文件，从源代码安装的命令为：
41+
42+
python setup.py install
43+
44+
> Python支持用户级安装。所谓用户级安装用于以下两种情形：
45+
>
46+
>* 当用户没有写`global site-packages`目录时
47+
>* 当用户不想安装在`global site-packages`目录时
48+
>
49+
> 用户级安装命令是在常规的`install`命令后添加`--user`选项。
50+
> 安装的目录由`PYTHONUSERBASE`环境变量决定（该环境变量影响的是`site.USER_BASE`变量的值
51+
52+
### 2.查看
53+
#### a. 查看某个已安装package
54+
查看某个package的详细信息命令为：
55+
56+
pip show SomePackage #查看该package详细信息
57+
pip show --files SomePackage #查看该package已安装哪些文件
58+
59+
#### b. 查看所有已经安装package
60+
查看已经安装了哪些package的命令为：
61+
62+
pip list #列出所有已安装的package
63+
pip list --outdated #列出所有outdated package
64+
65+
### 3.更新package
66+
更新package命令为：
67+
68+
pip install --upgrade SomePackage
69+
70+
### 4.卸载package
71+
72+
卸载package的命令为：
73+
74+
pip uninstall SomePackage
75+
76+
### 5.寻找package
77+
寻找package的命令为：
78+
79+
pip search "query"
80+
81+
## 三、配置文件
82+
配置文件有三个级别：系统级别、用户级别、virtualenv级别。其读取顺序为：首先读取系统级别的配置文件，然后读取用户级别的配置文件，最后读取virtualenv级别的配置文件。
83+
84+
如果同样的值在多个配置文件中设置，则最后读取的值会覆盖早期读取的值。
85+
86+
### 1.系统级的配置文件
87+
系统级的配置文件位于：
88+
89+
* Unix系统中位于：`/etc/pip.conf`。也可以位于由`XDG_CONFIG_DIRS`环境变量（若存在的话）
90+
指定的目录的名为`pip`的子目录中，如`/etc/xdg/pip/pip.conf`
91+
* OSX系统中位于： `/Library/Application Support/pip/pip.conf`
92+
* XP系统中位于：
93+
`C:\Documents and Settings\All Users\Application Data\pip\pip.ini`
94+
* Win7和以后的系统中是hidden的，但是可以写 `C:\ProgramData\pip\pip.ini`
95+
96+
> 系统级的配置文件不支持Windows Vista
97+
98+
### 2.用户级的的配置文件
99+
用户级的pip配置文件位于：
100+
101+
* Unix系统中位于：`$HOME/.config/pip/pip.conf`（由`XDG_CONFIG_HOME`环境变量指定的）
102+
* OSX系统中位于：`$HOME/Library/Application Support/pip/pip.conf`
103+
* Windows系统中位于：`%APPDATA%\pip\pip.ini`
104+
105+
> 你可以通过环境变量 `PIP_CONFIG_FILE` 来指定这个用户级别的配置文件的位置
106+
107+
### 3.virtualenv中的配置文件
108+
你可以在env中设置不同虚拟环境下的配置文件：
109+
110+
* 在Unix/OSX系统中位于：`$VIRTUAL_ENV/pip.conf`
111+
* 在Windows系统中位于： `%VIRTUAL_ENV%\pip.ini`
112+

‎packages/sphinx_usage.markdown

Lines changed: 125 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,125 @@
1+
# Sphinx 1.3.1
2+
3+
## 一、入门
4+
5+
1.Sphinx支持HTML、LaTex、man、纯文本输出。它使用结构化文本标记(reStructuredText)作为标记语言
6+
7+
2.Sphinx内置了一个`sphinx-quickstart`脚本用于自动生成默认的`conf.py`配置文件
8+
9+
* 包含所有原始文本的目录称为资源目录。该目录必须包含Sphinx配置文件`conf.py`
10+
* Sphinx根据`conf.py`的变量值来查阅和生成文档
11+
* Sphinx的`sphinx-quickstart`脚本除了自动生成`conf.py`之外还会生成一个主文档`index.rst`。主文档是欢迎页，它包含了`toctree`（即内容属索引）。主文档的初始内容为：
12+
13+
```
14+
.. toctree ::
15+
:maxdepth: 2
16+
```
17+
3.编译文档的命令：`sphinx-build -b html sourcedir builddir`
18+
19+
* `sourcedir`为源代码所在的目录，`builddir`为目标目录，通常该目录都命名为`doc`
20+
* `-b`指定了输出格式：
21+
* `html`：输出为HTML格式（默认行为）
22+
* `dirhtml`：输出为HTML格式，但是输出到单一目录中
23+
* `singlehtml`：输出为一个单页的HTML页面
24+
* `htmlhelp`、`qthelp`、`devhelp`、`epub` :构建为HTML文件并配合附加信息打包为上述指定的格式
25+
* `latex`：输出为Latex源码
26+
* `man`：输出为手册页面
27+
* `text`：输出为纯文本
28+
* `linkcheck`：检查所有外部链接的完整性，没有输出
29+
* `gettext`：输出为`.pot`文档
30+
* `doctest`：若`doctest`扩展已经激活，则执行所有文档中的`doctests`
31+
* `sphinx-quickstart`脚本已经创建了`Makefile`以及`make.bat`（Windows环境中），可以简单的使用命令`make html`构建
32+
33+
4.`conf.py`已经写入了相关配置项，你可以取消某些行的注释并修订参数值。
34+
> `conf.py`文件默认使用UTF-8编码保存。如果有参数值使用非ASCII字符，则必须用UNICODE形式
35+
36+
## 二、Autodoc
37+
1.对Python进行文档化时，常规做法是把大量内容直接填入源码各个字符串位置。Sphinx支持直接从模块中提取这种类型的文档，这通过Autodoc扩展来实现。
38+
39+
* 要使用autodoc扩展，必须在`conf.py`的`extensions`列表中包含`sphinx.ext.autodoc`
40+
* autodoc需要导入你的模块来加载文档字符串，因此你必须在配置文件`conf.py`的`sys.path`列表中追加目标模块所在的路径（如果该路径已存在与`sys.path`中，则不需要此步骤）
41+
42+
43+
2.添加docstring：在`data member`以及`class attribute`之后你都可以用`''' ...'''`添加文档字符串
44+
45+
```
46+
class Foo:
47+
'''
48+
This is docstring for Foo
49+
'''
50+
bar=1
51+
'''
52+
This is description for bar
53+
'''
54+
def __init__(self):
55+
'''
56+
This is description for __init__
57+
'''
58+
self.param=4
59+
'''
60+
This is description for param
61+
'''
62+
```
63+
* 在注释文字中，可以用reSt语法、Markdown语法
64+
* 模块的文档字符串必须放在文档的首行
65+
* 你也可以通过添加注释来完成文档化：注释要么在定义语句同一行，位于定义语句之后；要么在定义语句之前的一行或者几行
66+
67+
```
68+
class Foo: #This is comments for Foo ,must be one line
69+
# This is comment for bar in front of bar definine ,can bu multi line
70+
# This is comment for bar in front of bar definine ,can bu multi line
71+
bar=1
72+
def __init__(self):#This is comments for __init__ ,must be one line
73+
self.param=4#This is comments for param ,must be one line
74+
```
75+
76+
3.必须要用`sphinx-apidoc`脚本将python的docstring转换成`.rst`文档：
77+
78+
```
79+
sphinx-apidoc [options] -o outputdir packagedir [pathnames]
80+
```
81+
然后再运行`sphinx-build`才能生成`autodoc`
82+
83+
* `outputdir`：输出`.rst`文档的目录；`packagedir`：Python源文件的根目录
84+
* 通常把所有文档放在一个叫`doc`的目录中
85+
86+
4.autodoc生成的文件内容为：` .. automodule :: `：为`module`生成自动化文档； ` .. autoclass :: `：为`class`生成自动化文档； ` .. autoexception :: `：为`exception`生成自动化文档
87+
88+
* 其语义为：
89+
90+
```
91+
.. automodule :: modname
92+
:members:
93+
```
94+
会对`modname`这个模块生成自动化文档，并对其所有`member`（递归地）打文档（通过查看模块的`__all__`属性查找`member`）
95+
96+
```
97+
.. autoclass:: classname
98+
:members:
99+
```
100+
会对`classname`这个类生成自动化文档，会对`classname`类的所有非私有成员（即不是以`_`开头的成员）打文档
101+
* 你也可以显式指定`member`，此时只有指定的`member`打文档，其他的`member`不打文档：
102+
103+
```
104+
.. automodule :: modname
105+
:members: mod_member1,mod_member2
106+
```
107+
* 没有`docstring`的`member`默认不会打文档。若想增加对这些不带`docstring`的`member`打文档，可以用：
108+
109+
```
110+
.. automodule :: modname
111+
:members:
112+
:undoc-members:
113+
```
114+
115+
* 若添加`:private-members：`则会对私有成员（以`_`或者`__`开头的成员）打文档
116+
若添加`:special-members：`则会对特殊成员（以`__`开头且以`__`结尾的成员）打文档
117+
* 对于`class`与`exception`，`member`默认不包含基类的成员。若想添加基类的成员文档，
118+
则添加`:inherited-members:`
119+
* 若想排除某个指定`member`不打文档，则添加`:exclude-members: member1,member2`
120+
* `:show-inheritance:`选项会在每个`class`、`exception`文档后插入基类的信息
121+
122+
5.`autodoc`通过导入模块，然后观察`.__doc__`属性来生成docstring。因此如果你对使用了装饰器的函数、类打文档，必须在装饰器中拷贝被装饰函数、类的`.__doc__`属性
123+
124+
125+

‎packages/virtualenv_usage.markdown

Lines changed: 45 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,45 @@
1+
# VirtualEnv
2+
VirtualEnv用于创建独立的Python虚拟环境，这些独立的Python虚拟环境中有独立的安装目录。
3+
4+
## 一、安装VirtualEnv
5+
通过`pip install virtualenv`命令可以安装VirtualEnv
6+
7+
## 二、创建独立的Python虚拟环境
8+
创建独立的Python虚拟环境命令为：
9+
10+
virtualenv ENV
11+
12+
>如果你使用`virtualenv --system-site-packages ENV`命令创建Python虚拟环境，则该虚拟环境会继承来自`global site-packages`中的所有 packages.
13+
14+
其中`ENV`是新的虚拟环境的目录，该命令做了下面的事情：
15+
16+
* 创建`ENV/lib/`目录以及`ENV/include/`目录，它们包含用于支持Python虚拟环境所必须的
17+
library files。虚拟环境中安装的所有 package都位于
18+
`ENV/lib/pythonX.X/site-packages/` 目录下
19+
*
20+
* 在Unix/OSX系统上创建`ENV/bin/`目录，其中存放着Python虚拟环境所必须的可执行文件以及脚本。
21+
* 在Windows系统上创建`ENV\Scripts\`目录，其中存放着Python虚拟环境所必须的可执行文件以及脚本。
22+
* 安装关键的 pip 以及 setuptools 这两个 package。`ENV/bin/pip` 是与当前虚拟环境中相关的 pip
23+
24+
## 三、 激活Python虚拟环境
25+
在新创建的Python虚拟环境中，有一个激活脚本。
26+
27+
* 在 Posix系统上，该激活脚本位于`ENV/bin/activate`
28+
* 在 Windows系统中，激活脚本位于`ENV\Scripts\activate。bat`
29+
30+
激活Python虚拟环境命令为：
31+
32+
* 在 Posix 系统中，执行`source ENV/bin/activate`命令
33+
* 在 Windows 系统中，在CMD中执行`ENV\Scripts\activate.bat`脚本
34+
35+
>该脚本本质上是修改`$PATH`环境变量，使得环境变量的第一项为`ENV/bin/`目录。
36+
>同时修改你的SHELL命令提示符，从而提示你这是在一个Python虚拟环境中
37+
>
38+
>你也可以不使用该激活脚本，而是直接调用`bin/`目录中的脚本和python解释器(Unix/OSX环境下)
39+
>，如`ENV/bin/pip`以及 `ENV/bin/python-script.py`
40+
41+
## 四、退出虚拟环境
42+
退出虚拟环境，在shell中键入`deactivate`命令即可
43+
44+
## 五、移除Python虚拟环境
45+
移除之前首先退出Python虚拟环境，然后删除ENV文件夹即可

0 commit comments

Comments
 (0)