473,320 Members | 1,817 Online
Bytes | Software Development & Data Engineering Community
Post Job

Home Posts Topics Members FAQ

Join Bytes to post your question to a community of 473,320 software developers and data experts.

Standard way of documenting python code ?

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

/_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/
/ bu****@yahoo.fr
/
| www.bucodi.com - My work
\ www.ifrance/karamusique -- My hobby
\_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/
Jul 18 '05 #1
2 1489
Rony <bu****@ahoo.fr> writes:
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
Jul 18 '05 #2
John J. Lee wrote on 30 Nov 2003 15:30:28 +0000 in : <87************@pobox.com>
Rony <bu****@ahoo.fr> writes:
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

/_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/
/ bu****@yahoo.fr
/
| www.bucodi.com - My work
\ www.ifrance/karamusique -- My hobby
\_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/
Jul 18 '05 #3

This thread has been closed and replies have been disabled. Please start a new discussion.

Similar topics

8
by: Raymond Hettinger | last post by:
Comments are invited on the following proposed PEP. Raymond Hettinger ------------------------------------------------------- PEP: 329
5
by: Isaac Rodriguez | last post by:
Hi, Are there any standarized ways of documenting Python code? When I check the __doc__ attribute of the standard modules, the results are kind of plain. Is everyone using this style? Since...
2
by: Lasse Vågsæther Karlsen | last post by:
I notice that if I use this syntax: def classname: ... ## # closes the database connection and releases the resources. def close(self): .... ##
1
by: strauss.sean | last post by:
I have been asked to begin documenting the ongoing development and changes to a database that I maintain. Not the entry of data; this is about the changes to how tables are restructured, and any...
13
by: Jeff Rodriguez | last post by:
What sort of documentation do you do on your code? I've never done any code development on a big project and I want to start documenting my code in a way that makes sense, is easy to understand,...
8
by: Spleenwort | last post by:
With regard to XML comments in c#. I think that #regions should be self-documenting relative to XML comments or that a <region> tag should be defined and auto-inserted when you type #region...
7
by: Robert Seacord | last post by:
The CERT/CC has just deployed a new web site dedicated to developing secure coding standards for the C programming language, C++, and eventually other programming language. We have already...
9
by: Grizlyk | last post by:
Somebody have offered std colors to C++ in the msg here: http://groups.google.com/group/comp.lang.c++/browse_frm/thread/2e5bb3d36ece543b/1acf6cd7e3ebdbcd#1acf6cd7e3ebdbcd The main objection to...
20
by: Pilcrow | last post by:
This behavior seems very strange to me, but I imagine that someone will be able to 'explain' it in terms of the famous C standard. -------------------- code -----------------------------------...
0
by: ryjfgjl | last post by:
ExcelToDatabase: batch import excel into database automatically...
0
isladogs
by: isladogs | last post by:
The next Access Europe meeting will be on Wednesday 6 Mar 2024 starting at 18:00 UK time (6PM UTC) and finishing at about 19:15 (7.15PM). In this month's session, we are pleased to welcome back...
0
by: Vimpel783 | last post by:
Hello! Guys, I found this code on the Internet, but I need to modify it a little. It works well, the problem is this: Data is sent from only one cell, in this case B5, but it is necessary that data...
0
by: jfyes | last post by:
As a hardware engineer, after seeing that CEIWEI recently released a new tool for Modbus RTU Over TCP/UDP filtering and monitoring, I actively went to its official website to take a look. It turned...
0
by: ArrayDB | last post by:
The error message I've encountered is; ERROR:root:Error generating model response: exception: access violation writing 0x0000000000005140, which seems to be indicative of an access violation...
0
by: CloudSolutions | last post by:
Introduction: For many beginners and individual users, requiring a credit card and email registration may pose a barrier when starting to use cloud servers. However, some cloud server providers now...
0
by: Defcon1945 | last post by:
I'm trying to learn Python using Pycharm but import shutil doesn't work
0
by: af34tf | last post by:
Hi Guys, I have a domain whose name is BytesLimited.com, and I want to sell it. Does anyone know about platforms that allow me to list my domain in auction for free. Thank you
0
by: Faith0G | last post by:
I am starting a new it consulting business and it's been a while since I setup a new website. Is wordpress still the best web based software for hosting a 5 page website? The webpages will be...

By using Bytes.com and it's services, you agree to our Privacy Policy and Terms of Use.

To disable or enable advertisements and analytics tracking please visit the manage ads & tracking page.