跟老齐学Python之Python文档


Posted in Python onOctober 10, 2014

文档很重要。独孤九剑的剑诀、易筋经的心法、写着辟邪剑谱的袈裟,这些都是文档。连那些大牛人都要这些文档,更何况我们呢?所以,文档是很重要的。

文档,说白了就是用word(这个最多了)等(注意这里的等,把不常用的工具都等掉了,包括我编辑文本时用的vim工具)文本编写工具写成的包含文本内容但不限于文字的文件。有点??拢??碌哪康氖俏?搜辖鳎?呛恰W詈没故抢匆桓龈?萌诵欧?亩ㄒ澹?比皇抢醋晕??倏啤?/p>

软件文档或者源代码文档是指与软件系统及其软件工程过程有关联的文本实体。文档的类型包括软件需求文档,设计文档,测试文档,用户手册等。其中的需求文档,设计文档和测试文档一般是在软件开发过程中由开发者写就的,而用户手册等非过程类文档是由专门的非技术类写作人员写就的。

 

早期的软件文档主要指的是用户手册,根据Barker的定义,文档是用来对软件系统界面元素的设计、规划和实现过程的记录,以此来增强系统的可用性。而Forward则认为软件文档是被软件工程师之间用作沟通交流的一种方式,沟通的信息主要是有关所开发的软件系统。Parnas则强调文档的权威性,他认为文档应该提供对软件系统的精确描述。

 

综上,我们可以将软件文档定义为:
1.文档是一种对软件系统的书面描述;

2.文档应当精确地描述软件系统;

3.软件文档是软件工程师之间用作沟通交流的一种方式;

4.文档的类型有很多种,包括软件需求文档,设计文档,测试文档,用户手册等;

5.文档的呈现方式有很多种,可以是传统的书面文字形式或图表形式,也可是动态的网页形式

那么这里说的Python文档指的是什么呢?一个方面就是每个学习者要学习python,python的开发者们(他们都是大牛)给我们这些小白提供了什么东西没有?能够让我们给他们这些大牛沟通,理解python中每个函数、指令等的含义和用法呢?

有。大牛就是大牛,他们准备了,而且还不止一个。

查看python文档

真诚的敬告所有看本教程的诸位,要想获得编程上的升华,看文档是必须的。文档胜过了所有的教程和所有的老师以及所有的大牛。为什么呢?其中原因,都要等待看官看懂了之后,有了体会感悟之后才能明白。

python文档的网址:https://docs.python.org/2/,这是python2.x,从这里也可以找到python3.x的文档。

跟老齐学Python之Python文档

除了看网站上的文档,还有别的方式吗?

有,而且看官并不陌生,此前已经在本教程中多次用到,那就是dir()和help()

>>> dir(list)

['__add__', '__class__', '__contains__', '__delattr__', '__delitem__', '__delslice__', '__doc__', '__eq__', '__format__', '__ge__', '__getattribute__', '__getitem__', '__getslice__', '__gt__', '__hash__', '__iadd__', '__imul__', '__init__', '__iter__', '__le__', '__len__', '__lt__', '__mul__', '__ne__', '__new__', '__reduce__', '__reduce_ex__', '__repr__', '__reversed__', '__rmul__', '__setattr__', '__setitem__', '__setslice__', '__sizeof__', '__str__', '__subclasshook__', 'append', 'count', 'extend', 'index', 'insert', 'pop', 'remove', 'reverse', 'sort']
>>> help(list.__mul__)
Help on wrapper_descriptor:
__mul__(...)

    x.__mul__(n) <==> x*n

 这种查看文档的方式,在交互模式下经常用到,快捷方便,请看官务必牢记并使用。

正如前面已经介绍过的,还有一个文档:doc,help调用的其实就是这个函数里面的内容。

>>> print(list.__mul__.__doc__)     #与help(list.__mul__)显示的内容一致

x.__mul__(n) <==> x*n
>>> print(list.index.__doc__)       #查看index的文档

L.index(value, [start, [stop]]) -> integer -- return first index of value.

Raises ValueError if the value is not present.

 给自己的程序加上文档

在自己编写程序的时候,也非常希望能够有类似上面查看python文档的功能,可以通过某种方式查看自己的程序文档,这样显得自己多牛呀。

有一种方法可以实现,就是在你所编写的程序中用三个双引号或者单引号成对地出现,中间写上有关文档内容。

>>> def qiwsir():

...     """I like python"""

...     print "http://qiwsir.github.io"

... 

>>> qiwsir()
http://qiwsir.github.io
>>> print(qiwsir.__doc__)   #用这种方法可以看自己写的函数中的文档

I like python
>>> help(qiwsir)            #其实就是调用__doc__显示的内容
Help on function qiwsir in module __main__:
qiwsir()

    I like python

 另外,对于一个文件,可以把有关说明放在文件的前面,不影响该文件代码运行。

例如,有这样一个扩展名是.py的python文件,其内容是:

#!/usr/bin/env python

#coding:utf-8
import random
number = random.randint(1,100)
guess = 0
while True:
    num_input = raw_input("please input one integer that is in 1 to 100:")

    guess +=1
    if not num_input.isdigit():

        print "Please input interger."

    elif int(num_input)<0 and int(num_input)>=100:

        print "The number should be in 1 to 100."

    else:

        if number==int(num_input):

            print "OK, you are good.It is only %d, then you successed."%guess

            break

        elif number>int(num_input):

            print "your number is more less."

        elif number<int(num_input):

            print "your number is bigger."

        else:

            print "There is something bad, I will not work"

 这段程序,就是在《用while来循环》中用到的一个猜数字的游戏,它存储在名为205-2.py的文件中,如果要对这段程序写一个文档,就可以这么做。

"""

   This is a game.

   I am Qiwei.

   I like python.

   I am writing python articles in my website.

   My website is http://qiwsir.github.io

   You can learn python free in it.

"""
#!/usr/bin/env python

#coding:utf-8
import random
number = random.randint(1,100)
guess = 0
while True:
    num_input = raw_input("please input one integer that is in 1 to 100:")

    guess +=1
    if not num_input.isdigit():

        print "Please input interger."

    elif int(num_input)<0 and int(num_input)>=100:

        print "The number should be in 1 to 100."

    else:

        if number==int(num_input):

            print "OK, you are good.It is only %d, then you successed."%guess

            break

        elif number>int(num_input):

            print "your number is more less."

        elif number<int(num_input):

            print "your number is bigger."

        else:

            print "There is something bad, I will not work"

 最后,推荐一片相当相当好的文章,与列位分享:

Python 自省指南:如何监视您的 Python 对象

Python 相关文章推荐
简单的连接MySQL与Python的Bottle框架的方法
Apr 30 Python
详解Python中的元组与逻辑运算符
Oct 13 Python
python实现字符串连接的三种方法及其效率、适用场景详解
Jan 13 Python
Python实现批量压缩图片
Jan 25 Python
python爬虫实例详解
Jun 19 Python
使用pandas批量处理矢量化字符串的实例讲解
Jul 10 Python
python爬虫神器Pyppeteer入门及使用
Jul 13 Python
python rsa实现数据加密和解密、签名加密和验签功能
Sep 18 Python
Python3 A*寻路算法实现方式
Dec 24 Python
PyCharm设置Ipython交互环境和宏快捷键进行数据分析图文详解
Apr 23 Python
Python pexpect模块及shell脚本except原理解析
Aug 03 Python
python 录制系统声音的示例
Dec 21 Python
跟老齐学Python之大话题小函数(2)
Oct 10 #Python
跟老齐学Python之大话题小函数(1)
Oct 10 #Python
Python警察与小偷的实现之一客户端与服务端通信实例
Oct 09 #Python
python中二维阵列的变换实例
Oct 09 #Python
python实现每次处理一个字符的三种方法
Oct 09 #Python
Python正则表达式匹配ip地址实例
Oct 09 #Python
Python数据结构之Array用法实例
Oct 09 #Python
You might like
mysq GBKl乱码
2006/11/28 PHP
PHP超牛逼无限极分类生成树方法
2015/05/11 PHP
Yii遍历行下每列数据的方法
2016/10/17 PHP
PHP数组基本用法与知识点总结
2020/06/02 PHP
判断多个input type=file是否有已经选择好文件的代码
2012/05/23 Javascript
js移除事件 js绑定事件实例应用
2012/11/28 Javascript
jquery常用特效方法使用示例
2014/04/25 Javascript
node.js中的url.resolve方法使用说明
2014/12/10 Javascript
JavaScript知识点总结(十六)之Javascript闭包(Closure)代码详解
2016/05/31 Javascript
javascript this详细介绍
2016/09/19 Javascript
javascript trie前缀树的示例
2018/01/29 Javascript
vue表单自定义校验规则介绍
2018/08/28 Javascript
解决vue路由后界面没有变化,但是链接有的问题
2018/09/01 Javascript
微信小程序授权登录解决方案的代码实例(含未通过授权解决方案)
2019/05/10 Javascript
mock.js模拟前后台交互
2019/07/25 Javascript
浅谈javascript错误处理
2019/08/11 Javascript
JS实现随机抽选获奖者
2019/11/07 Javascript
vue.js的状态管理vuex中store的使用详解
2019/11/08 Javascript
微信小程序中target和currentTarget的区别小结
2020/11/06 Javascript
Vue3 响应式侦听与计算的实现
2020/11/11 Javascript
easy_install python包安装管理工具介绍
2013/02/10 Python
wxPython窗口的继承机制实例分析
2014/09/28 Python
python搭建微信公众平台
2016/02/09 Python
浅析Python中的getattr(),setattr(),delattr(),hasattr()
2016/06/14 Python
Python+OpenCV目标跟踪实现基本的运动检测
2018/07/10 Python
Pycharm打开已有项目配置python环境的方法
2020/07/03 Python
Python数据可视化常用4大绘图库原理详解
2020/10/23 Python
CSS3制作炫酷的自定义发光文字
2016/03/28 HTML / CSS
Stio官网:男女、儿童户外服装
2019/12/13 全球购物
个人贷款承诺书
2014/03/28 职场文书
2015年初中元旦晚会活动总结
2014/11/28 职场文书
让子弹飞观后感
2015/06/11 职场文书
2016优秀大学生个人事迹材料范文
2016/03/01 职场文书
CSS使用伪类控制边框长度的方法
2022/01/18 HTML / CSS
baselines示例程序train_cartpole.py的ImportError
2022/05/20 Python
Android Studio 计算器开发
2022/05/20 Java/Android