跟老齐学Python之Python文档

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

文档,说白了就是用word(这个最多了)等(注意这里的等,把不常用的工具都等掉了,包括我编辑文本时用的vim工具)文本编写工具写成的包含文本内容但不限于文字的文件。有点啰嗦,啰嗦的目的是为了严谨,呵呵。最好还是来一个更让人信服的定义,当然是来自维基百科。

代码如下:

软件文档或者源代码文档是指与软件系统及其软件工程过程有关联的文本实体。文档的类型包括软件需求文档,设计文档,测试文档,用户手册等。其中的需求文档,设计文档和测试文档一般是在软件开发过程中由开发者写就的,而用户手册等非过程类文档是由专门的非技术类写作人员写就的。
 
早期的软件文档主要指的是用户手册,根据Barker的定义,文档是用来对软件系统界面元素的设计、规划和实现过程的记录,以此来增强系统的可用性。而Forward则认为软件文档是被软件工程师之间用作沟通交流的一种方式,沟通的信息主要是有关所开发的软件系统。Parnas则强调文档的权威性,他认为文档应该提供对软件系统的精确描述。
 
综上,我们可以将软件文档定义为:

1.文档是一种对软件系统的书面描述;
2.文档应当精确地描述软件系统;
3.软件文档是软件工程师之间用作沟通交流的一种方式;
4.文档的类型有很多种,包括软件需求文档,设计文档,测试文档,用户手册等;
5.文档的呈现方式有很多种,可以是传统的书面文字形式或图表形式,也可是动态的网页形式

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

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

查看python文档

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

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

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

有,而且看官并不陌生,此前已经在本教程中多次用到,那就是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 对象

(0)

相关推荐

  • 跟老齐学Python之传说中的函数编写条规

    关于函数的事情,总是说不完的,下面就罗列一些编写函数的注意事项.特别声明,这些事项不是我总结的,我是从一本名字为<Learning Python>的书里面抄过来的,顺便写成了汉语,当然,是按照自己的视角翻译的,里面也夹杂了一些自己的观点.看官也可以理解为源于<Learning Python>但又有点儿不同.  •函数具有独立性.也就是常说的不要有太强的耦合性.要让函数能够独立于外部的东西.参数和return语句就是实现这种独立性的最好方法.  •尽量不要使用全局变量,这也是让函数具

  • 跟老齐学Python之重回函数

    函数的基本结构 Python中的函数基本结构: 复制代码 代码如下: def 函数名([参数列表]):     语句 几点说明:  •函数名的命名规则要符合python中的命名要求.一般用小写字母和单下划线.数字等组合  •def是函数的开始,这个简写来自英文单词define,显然,就是要定义一个什么东西  •函数名后面是圆括号,括号里面,可以有参数列表,也可以没有参数  •千万不要忘记了括号后面的冒号  •语句,相对于def缩进,按照python习惯,缩进四个空格 看简单例子,深入理解上面的要

  • 跟老齐学Python之关于类的初步认识

    在开始部分,请看官非常非常耐心地阅读下面几个枯燥的术语解释,本来这不符合本教程的风格,但是,请看官谅解,因为列位将来一定要阅读枯燥的东西的.这些枯燥的属于解释,均来自维基百科. 1.问题空间 问题空间是问题解决者对一个问题所达到的全部认识状态,它是由问题解决者利用问题所包含的信息和已贮存的信息主动地构成的. 一个问题一般有下面三个方面来定义:  •初始状态--一开始时的不完全的信息或令人不满意的状况:  •目标状态--你希望获得的信息或状态:  •操作--为了从初始状态迈向目标状态,你可能采取的

  • 跟老齐学Python之大话题小函数(1)

    开篇就要提到一个大的话题:编程范型.什么是编程范型?引用维基百科中的解释: 复制代码 代码如下: 编程范型或编程范式(英语:Programming paradigm),(范即模范之意,范式即模式.方法),是一类典型的编程风格,是指从事软件工程的一类典型的风格(可以对照方法学).如:函数式编程.程序编程.面向对象编程.指令式编程等等为不同的编程范型. 编程范型提供了(同时决定了)程序员对程序执行的看法.例如,在面向对象编程中,程序员认为程序是一系列相互作用的对象,而在函数式编程中一个程序会被看作是

  • 跟老齐学Python之让人欢喜让人忧的迭代

    哦,这就是真正牛X的程序员.不过,他也仅仅是牛X罢了,还不是大神.大神程序员是什么样儿呢?他是扫地僧,大隐隐于市. 先搞清楚这些名词再说别的: 循环(loop),指的是在满足条件的情况下,重复执行同一段代码.比如,while语句. 迭代(iterate),指的是按照某种顺序逐个访问列表中的每一项.比如,for语句. 递归(recursion),指的是一个函数不断调用自身的行为.比如,以编程方式输出著名的斐波纳契数列. 遍历(traversal),指的是按照一定的规则访问树形结构中的每个节点,而且

  • 跟老齐学Python之大话题小函数(2)

    上一讲和本讲的标题是"大话题小函数",所谓大话题,就是这些函数如果溯源,都会找到听起来更高大上的东西.这种思维方式绝对我坚定地继承了中华民族的优良传统的.自从天朝的臣民看到英国人开始踢足球,一直到现在所谓某国勃起了,都一直在试图论证足球起源于该朝的前前前朝的某国时代,并且还搬出了那时候的一个叫做高俅的球星来论证,当然了,勃起的某国是挡不住该国家队在世界杯征程上的阳痿,只能用高俅来意淫一番了.这种思维方式,我是坚定地继承,因为在我成长过程中,它一直被奉为优良传统.阿Q本来是姓赵的,和赵老

  • 跟老齐学Python之总结参数的传递

    就前面所讲,函数的基本内容已经完毕.但是,函数还有很多值得不断玩味的细节.这里进行阐述. 参数的传递 python中函数的参数通过赋值的方式来传递引用对象.下面总结通过总结常见的函数参数定义方式,来理解参数传递的流程. def foo(p1,p2,p3,...) 这种方式最常见了,列出有限个数的参数,并且彼此之间用逗号隔开.在调用函数的时候,按照顺序以此对参数进行赋值,特备注意的是,参数的名字不重要,重要的是位置.而且,必须数量一致,一一对应.第一个对象(可能是数值.字符串等等)对应第一个参数,

  • 跟老齐学Python之变量和参数

    那么什么这两个到底有什么区别和联系呢?我在网上搜了一下,发现很多说法,虽然大同小异,但是似乎只有下面这一段来自微软网站的比较高度抽象,而且意义涵盖深远.我摘抄过来,看官读一读,是否理解,虽然是针对VB而言的,一样有启发. 复制代码 代码如下: 参数和变量之间的差异 (Visual Basic) 多数情况下,过程必须包含有关调用环境的一些信息.执行重复或共享任务的过程对每次调用使用不同的信息.此信息包含每次调用过程时传递给它的变量.常量和表达式. 若要将此信息传递给过程,过程先要定义一个形参,然后

  • 用python将word文档合并实例代码

    目录 背景: 设计思路: 脚本环境说明: 完整代码: 功能执行效果图: 总结: 背景:         由于工作需要,现在有这么一个需求,要合并大量的word文档,而且要在不同的目录下找到同一个人的word文档,进行合并,最终输出一个合并后的word文档.一般来说几个或者十几个量不多的话,就手工合并一下好了,但现在这个量是真的大.目录有十多个,每个目录又有50多个不同人的word文档,而且同一个人在不同目录下又不一定都有word文档,因此,整个合并工作就出现了人工操作的困难: 工作量多:容易疏漏

  • python读取word文档的方法

    本文实例讲述了python读取word文档的方法.分享给大家供大家参考.具体如下: 首先下载安装win32com from win32com import client as wc word = wc.Dispatch('Word.Application') doc = word.Documents.Open('c:/test') doc.SaveAs('c:/test.text', 2) doc.Close() word.Quit() 这种方式产生的text文档,不能用python用普通的r方

  • Python实现pdf文档转txt的方法示例

    本文实例讲述了Python实现pdf文档转txt的方法.分享给大家供大家参考,具体如下: 首先,这是一个比较粗糙的版本,因为已经够用了,而且对pdf的格式不熟悉,所以暂时没有进一步优化. 还有,这是转成txt的,所以如果是有图片的pdf是无法保存图片的. 至于本来就是图片的文本,这里是无法分析出来的.那些图片的pdf,估计要用图形匹配的方式来处理,类似于超速拍摄的车牌识别. 不过这样的程度,已经不是文本处理了.扯远了... 转出来的文字,好像按照pdf里面的所展示的来换行了,看不到有什么规则还原

  • python对excel文档去重及求和的实例

    废话不多说,估计只有我这个菜鸟废了2个小时才搞出来,主要是我想了太多方法来实现,最后都因为这因为那的原因失败了 间接说明自己对可变与不可变类型的了解,还是不够透彻 最后就用了个笨方法解决了! #coding:utf-8 import xlrd import xlwt import os from collections import Counter workbook = xlrd.open_workbook(r'D:\hh\heli\a.xlsx') Sheet1 = workbook.shee

  • 利用Python读取txt文档的方法讲解

    在G:/PythonPractise文件夹下新建一个名为record.txt的文本文档,写入如下图所示四行内容并保存. 打开python3的idle,开始写代码. 方法一代码和运行结果如下: 如上面运行结果所示,上面的结果是省略end=的写法,等价于end="\n"(回车); 下面的结果是end=""(空字符串)的写法,等价于end="\r"(换行) 方法二代码和运行结果如下: 方法三代码结果如下: 比较三种方法,方法一先将该路径下的文件返回成一

  • Python对excel文档的操作方法详解

    本文实例讲述了Python对excel文档的操作方法.分享给大家供大家参考,具体如下: pip安装python库:(linux命令行输入不要在idle输入) pip install xlrd pip install xlwd 1.获取excel中的数据 利用xlrd模块读取并简单操作excel文档: 1.打开excel文档 import xlrd workbook = xlrd.open_workbook("test_case.xlsx") 2.获取所有的sheet表 sheet_na

  • python读取word文档,插入mysql数据库的示例代码

    表格内容如下: 1.实现批量导入word文档,取文档标题中的数字作为编号 2.除取上面打钩的内容需要匹配出来入库入库,其他内容全部直接入库mysql # wuyanfeng # -*- coding:utf-8 -*- # 读取docx中的文本代码示例 import docx import pymysql import re import os # 创建数据库链接 conn = pymysql.connect( host='rm-bp1vu5d84dg12c6d59o.mysql.rds.ali

  • python将txt文档每行内容循环插入数据库的方法

    如下所示: import pymysql import time import re def get_raw_label(rece): re1 = r'"([\s\S]*?)": "' #-------------正则表达式 reg1 = re.compile(re1) # ------------编译一下 str1 = reg1.findall(rece) return str1 def get_detail(rece): re2 = r'": "([\

  • python输出pdf文档的实例

    python导出pdf,参考诸多资料,发现pdfkit是效果比较好的. 故下载后进行了实现,多次失败后终于成功了,现将其中经验总结如下: """ 需要安装pdfkit,另外需要安装可执行文件wkhtmltopdf.exe, pdfkit核心命令是调用wkhtmltopdf.exe实现转pdf 有三个接口: pdfkit.from_url pdfkit.from_string pdfkit.from_file 需要注意的是,pdfkit主要是用来将html转pdf,所以文件也是

  • python实现word文档批量转成自定义格式的excel文档的思路及实例代码

    支持按照文件夹去批量处理,也可以单独一个文件进行处理,并且可以自定义标识符 最近在开发一个答题类的小程序,到了录入试题进行测试的时候了,发现一个问题,试题都是word文档格式的,每份有100题左右,拿到的第一份试题,光是段落数目就有800个.而且可能有几十份这样的试题. 而word文档是没有固定格式的,想批量录入关系型数据库mysql,必须先转成excel文档.这个如果是手动一个个粘贴到excel表格,那就头大了. 我最终需要的excel文档结构是这样的:每道题独立占1行,每1列是这道题的一项内

随机推荐