[Sugar-devel] [PATCH] Calculate/functions.py

[Tim McNamara]

This commit makes several significant changes to this
file. Overall, the desire was to aid compliance with
PEP-0257. Along the way, a number of other possible
enhancements were noted.

Changes include
  - encoding declaration
  - module docstrings
  - function docstrings
  - minor changes to functions
  - whitespace removal

Module docstring
  - added

Function docstrings
  - have been made much more verbose

Docstrings remain available to gettext. I have changed the
pattern from:

  def spam(eggs):
      return eggs.with_spam()
  spam.__doc__ = gettext('Comments here')

to:

  def spam(eggs):
      """
      comments here
      """
      return eggs.with_spam()
  spam.__doc__ = gettext(spam.__doc__)

In order to keep with the theme of allowing the docstrings
to be educational, I have included links to the English
Wikipedia where appropriate (and where it was easy for me to
do.)

Doctests now cover most of the non-trival problems, such as
direct calls thorough to Python's math module. Test coverage
has moved from 0% to ~50%.

Function changes
  -  ceil()
      - now returns integer as described in
        function's documentation
  -  _do_gcd(a, b)
      - removed reference to "self",
        given that the function is not in a class
  -  gcd(self, a, b)
      - removed reference to "self", given that
        the function is not in a class
      - changed ValueError to TypeError
      - added helpful exception message
  -  factorial
      - removed gettext from exception
      - changed ValueError to TypeError
  -  factorize
      - added option to return a list of factors
      - kept defaults to string representation
        for backwards compatibility
      - non-integers now raise a TypeError, rather
        than returning 0
  -  fac
      - now indicates that it is an alias of
        factorial in its docstring
  -  floor
      - now returns int as per documentation
      - removed float type coercion for values being sent to math.floor()
  -  mod
      - changed ValueError to TypeError
  -  round
      - returns an integer as per function's documentation
  -  shift_left & shift_right
      - ValueError to TypeError
  -  sqrt
      - removed type coercion, after 100,000 tests,
        results were equivalent without it
-------------- next part --------------
An HTML attachment was scrubbed...
URL: http://lists.sugarlabs.org/archive/sugar-devel/attachments/20100602/7b6381b3/attachment-0001.htm 
-------------- next part --------------
A non-text attachment was scrubbed...
Name: 0001-Code-docstrings-cleanup-added-doctests.patch
Type: text/x-diff
Size: 23224 bytes
Desc: not available
Url : http://lists.sugarlabs.org/archive/sugar-devel/attachments/20100602/7b6381b3/attachment-0001.patch