I haven't used
Python in a while. I'm logging my re-familiarization on the REPL and Doc Strings.
REPL
I write my code in
emacs and run it on the REPL instead of just doing ./my_code.py. I use
execfile to load my code:
$ ls -l my_code.py
-rwx------ 1 user user 3305 May 29 10:17 my_code.py
$ python
Python 2.4.3 (#1, Dec 11 2006, 11:38:52)
[GCC 4.1.1 20061130 (Red Hat 4.1.1-43)] on linux2
Type "help", "copyright", "credits" or "license" for more information.
>>> execfile("my_code.py")
>>> call_a_function_defined_in_my_code()
>>>
In emacs
M-x py-shell will get you a local Python REPL and you can
C-x o in a split screen between the REPL and your code (for mouse free development). I like to use
tramp to edit remote files. To accommodate this style with the py-shell I just ssh from
ansi-term and start the REPL as above.
Doc Strings
I tend to include a lot of comments when I define functions. My typical function looks like this:
# -------------------------------------------------------
def my_function():
"""
Function: my_function
Description: 1-3 line description of
the function... with an
extra line here...
Parameters:
[in] string $url The URL for x
[in] array $arr An associative array of y
[in] int $num The amount of z
(in) boolean $flag An optional flag to do k
(Default: false)
(in) string $name An optional name
(Default: "Larry")
Return Values:
interger -1 if an error occured
0 if authentication failed
1 on sucess
Remarks:
None
"""
# ---------------------------------------------------
# first line here
I can view this with Python's __doc__ attribute:
>>> print my_function.__doc__
Function: my_function
Description: 1-3 line description of
the function... with an
extra line here...
Parameters:
[in] string $url The URL for x
[in] array $arr An associative array of y
[in] int $num The amount of z
(in) boolean $flag An optional flag to do k
(Default: false)
(in) string $name An optional name
(Default: "Larry")
Return Values:
interger -1 if an error occured
0 if authentication failed
1 on sucess
Remarks:
None
>>>
The following
elisp allows me to
M-x function-template to easily place the above template in a python-mode buffer.
(defvar py-indent-offset 4
"*Indentation increment in Python mode")
(defun function-template ()
"creates a template for a function in: PHP, Perl or Python"
(interactive)
(if (eq major-mode 'python-mode)
(progn
(line line-length-default)
(insert-string "def my_function():\n")))
(save-excursion
(let ((pos (point)))
(if (eq major-mode 'python-mode)
(progn
(insert-string "\"\"\"\n")
(insert-string "Function: my_function\n\n"))
(progn
(line-no-comment line-length-default))
(insert-string "Function: Class::MyFunction\n\n"))
(insert-string "Description: 1-3 line description of \n")
(insert-string " the function... with an \n")
(insert-string " extra line here... \n\n")
; (insert-string "Type: public\n\n")
(insert-string "Parameters:\n")
(insert-string " [in] string $url The URL for x\n")
(insert-string " [in] array $arr An associative array of y\n")
(insert-string " [in] int $num The amount of z\n")
(insert-string " (in) boolean $flag An optional flag to do k\n")
(insert-string " (Default: false)\n")
(insert-string " (in) string $name An optional name\n")
(insert-string " (Default: \"Larry\")\n")
(insert-string "\n")
(insert-string "Return Values: \n")
(insert-string " interger -1 if an error occured\n")
(insert-string " 0 if authentication failed\n")
(insert-string " 1 on sucess\n")
(insert-string "\n")
(insert-string "Remarks: \n")
(insert-string " None \n")
(if (eq major-mode 'python-mode)
(progn
(insert-string "\"\"\"\n")
(line (- line-length-default py-indent-offset))
(insert-string "# first line here\n")
(indent-rigidly pos (point) py-indent-offset))
(progn
(line-no-comment line-length-default)
(comment-region pos (point))))
(if (eq major-mode 'php-mode)
(progn
(insert-string "\nfunction MyFunction() {\n")
(insert-string "\n}\n\n")))
(if (eq major-mode 'perl-mode)
(progn
(insert-string "\nsub MyFunction {\n")
(insert-string " my ($param1, $param2, ..., $paramn) = @_;\n\n")
(insert-string "\n}\n\n")))
(if (not (eq major-mode 'python-mode))
(indent-region pos (point) nil)))))
I've attempted to incorporate my style into conformance with the
Python Style Guide and borrowed a little from Tim Peters' improved Emacs Python mode
suggestion.
