Standard way of documenting python code ?

R

Rony

A question on python source documentation.
Does there exist a standard for documenting code ?
I've included here an example generated by pydoc of one of my modules.
Is this the right way or is it overkill ?
Comments are appreciated

Thanks,

Rony

Help on module sqlquery:

NAME
sqlquery

FILE
m:\plymouth\sqlquery.py

DESCRIPTION

#########################################################################
# Module : sqlquery.py
# Abstract : General, simple, SQL class
# Contains some simple classes
# connection(connectstring): connect to db and define
cursor
# cmd(command,logflag=None) : execute sql-command
# selcmd(dict,logflag=None) : execute select statement
# inscmd(dict,logflag=None) : execute insert statement
# Dependancies : mylibs.sqlerreur.py
# mylibs.string_man.py

#########################################################################

CLASSES
connection

class connection
| Connection to odbc source defined in connecstring
| Public methods :
| - close : close connection
| - cmd : execute cmd and return result set
|
| Methods defined here:
|
| __init__(self, connectstring)
| Create db connection from connectstring
| Connect string must have the format 'odbc-source/user'
| Will create cursor called self.cursor
|
| close(self)
| Close database connection
|
| cmd(self, command, logresult=None)
| Execute a SQL-statement, returns the resultset als list
| if logresult != None then write result in log.txt
|
| inscmd(self, dict, logresult=None)
| Execute a INSERT command.
| The command is constructed out of a dictionary (dict)
| The dict should contain :
| "tocols" : list of destination cols as a string
| "tables" : table where to insert as a string
| "values" : list of values to insert as a string
| Ex :
| {'tocols':'AC_ID,AC_NOM',
| 'table':'TBL_ACHETEUR',
| 'values':'1,'+quote('RONY')}
| will create : INSERT INTO TBL_ACHETEUR (AC_ID,AC_NOM)
| VALUES(1,'RONY)
| If logresult != None then write result in log.txt
| Returns nothing
|
| selcmd(self, dict, logresult=None)
| Execute a SELECT command.
| The command is constructed out of a dictionary (dict)
| The dict should contain :
| "cols" : list of cols as a string
| "tables" : list of tables as a string
| "order" : list of orders as a string
| Ex :
| {'cols':'AC_ID,AC_NOM',
| 'tables':'TBL_ACHETEUR',
| 'order':'AC_ID'}
| will create : SELECT AC_ID,AC_NOM FROM TBL_ACHETEUR
| ORDER BY AC_ID
| If logresult != None then write result in log.txt
| Returns self.result

DATA
achtdict = {'cols': 'AC_ID,AC_NOM', 'order': 'AC_NOM', 'tables':
'TBL_...
connectstring = 'plymouth/sa/'
insachdict = {'tables': 'TBL_TMP', 'tocols': 'TP_ID,TP_NOM',
'values':...



--
Rony

/_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/
/ (e-mail address removed)
/
| www.bucodi.com - My work
\ www.ifrance/karamusique -- My hobby
\_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/
 
J

John J. Lee

Rony said:
A question on python source documentation.
Does there exist a standard for documenting code ?
I've included here an example generated by pydoc of one of my modules.
Is this the right way or is it overkill ?
Comments are appreciated
[...]

http://www.python.org/peps/pep-0008.html

There are some good guidelines about docstrings in there.

If you're writing in English, error is spelled "error", not
"erreur". :)


John
 
R

Rony

John J. Lee wrote on 30 Nov 2003 15:30:28 +0000 in : said:
Rony said:
A question on python source documentation.
Does there exist a standard for documenting code ?
I've included here an example generated by pydoc of one of my modules.
Is this the right way or is it overkill ?
Comments are appreciated
[...]

http://www.python.org/peps/pep-0008.html

There are some good guidelines about docstrings in there.

If you're writing in English, error is spelled "error", not
"erreur". :)


John

Thanks for the link.
Oh BTW 'erreur' of 'error' ? In both cases it won't be wrong , no? ;)


--
Rony

/_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/
/ (e-mail address removed)
/
| www.bucodi.com - My work
\ www.ifrance/karamusique -- My hobby
\_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/
 

Ask a Question

Want to reply to this thread or ask your own question?

You'll need to choose a username for the site, which only take a couple of moments. After that, you can post your question and our members will help you out.

Ask a Question

Members online

No members online now.

Forum statistics

Threads
473,733
Messages
2,569,440
Members
44,832
Latest member
GlennSmall

Latest Threads

Top