sympy-0.5.14.tar.gz

.. _patches-tutorial: ====================== SymPy Patches Tutorial ====================== (`printable version`_) .. _printable version: spt-printable.html .. TODO reenable it when we fix sidebar handling in sphinx .. .. sidebar:: Talk is cheap. Show me the code. .. epigraph:: Talk is cheap. Show me the code. -- Linus Torvalds [1]_ .. role:: input(strong) Introduction ============ In SymPy_ we encourage collaborative work. Everyone is welcome to join and to implement new feature, fix some bug, give general advice, etc... Also, we try to discuss everything and to review each other's work so that many eyes can see more thus raising the quality. General discussion takes place on `sympy@googlecode.com`_ mailing list and in the issues_, and the code is discussed in `sympy-patches@googlecode.com`_ mailing list. As someone of you already know, software development is not just coding. A lot of non-coding tasks have to be done in order to produce *good* code. Just to mention a few: setting up infrastructure, designing, testing, documenting, assisting new developers (we are doing it here), and of course programming. But even programming is not all about writing the code, it is about writing the code *and* preparing it so that the code can be included into the project. Both producing the code and bringing it to the project are important parts of the game -- without the code there is nothing to bring in, and having the code outside is a nowin for anyone. As already said above, we review changes. This idea was borrowed from successful projects like Linux, Python, SAGE and a lot more. In short each change is first reviewed by other developers and only when it is approved the code is pushed in. Like it takes effort to write good and clear code, reviewing other's work needs effort too. There are good practices how to do things so that reviewing is fun for both the author and the reviewer. We try to follow them, and we'll try to show you how to follow too. This tutorial will guide you how to do SymPy development with Mercurial and patches. .. .. sidebar:: By the way .. admonition:: By the way when reviewing other's patches you *learn* a lot, so why not to join as a reviewer too? .. _SymPy: http://sympy.org/ .. _issues: http://code.google.com/p/sympy/issues/list .. _sympy@googlecode.com: http://groups.google.com/group/sympy .. _sympy-patches@googlecode.com: http://groups.google.com/group/sympy-patches Workflow ======== Here we'll describe the workflow using real world example where we fix some bug. Hacking ------- Suppose I want to fix issue `#755` .. image:: pics/1b.png I go there .. image:: pics/2.png Look at the problem description .. image:: pics/3b.png ... .. image:: pics/4b.png Aah, it looks like printing code in `sympy/printing/printer.py` tries to treat `expr` as an instance of a new-style class. I think I know how to fix this! .. image:: pics/5b.png Ok, going to dive into the problem. First of all there exist two approaches to work: 1. doing all the work in one repository, and 2. creating new repository for each task In practice both of them have pros and cons, but we'll consider the second one as it does the job and is simpler. So, let's clone main repo, and go hacking .. admonition:: By the way if you haven't already done so, do .. parsed-literal:: $ :input:`hg clone http://hg.sympy.org/sympy` .. parsed-literal:: $ :input:`hg clone sympy sympy-fix755` updating working directory 386 files updated, 0 files merged, 0 files removed, 0 files unresolved $ :input:`cd sympy-fix755` .. note:: This is a real-life example. If you want to repeat the exact steps, update your working directory to 4962f6641827 revision now: .. parsed-literal:: $ :input:`hg up 4962f6641827` I use vim_ editor, and usually it is very handy to navigate by tags, so I build tags database first, then invoke my editor [2]_ .. parsed-literal:: $ :input:`ctags -R` $ :input:`vim` It was in `_print` function, so I locate it using tags .. image:: pics/6.png here it is .. image:: pics/7.png and here is the failing code .. image:: pics/8.png Aah, it seems old classes do not have the attribute `__class__`. Let's see if this is the gist of the problem. .. parsed-literal:: $ :input:`./bin/isympy` In [1]: :input:`class C: pass` ...: In [2]: :input:`C` --------------------------------------------------------------------------- exceptions.AttributeError Traceback (most recent call last) ... AttributeError: class C has no attribute '__class__' Yes, it is. So I change it to what would always work. Then I invoke `hq` [3]_ to see what I've changed: .. parsed-literal:: $ :input:`hq` .. image:: pics/9.png and its time to see whether this fixes the problem .. parsed-literal:: In [1]: :input:`import sympy` In [2]: :input:`sympy.__dict__` oops, another bug seems to be sitting there: .. image:: pics/10.png after some examination it turned out to be a problem related to pretty-printing of sequences with even height .. parsed-literal:: In [3] :input:`{x**2: 1}` --------------------------------------------------------------------------- exceptions.ValueError Traceback (most recent call last) ... ValueError: xobj: expect length = 2*k+1 I decided to add another row for this case .. parsed-literal:: $ :input:`hqq` # `full diff at this stage`_ .. _full diff at this stage: spt-patches/1.patch .. image:: pics/11.png since after all it looks good: .. parsed-literal:: In [1]: :input:`[x**2]` Out[1]: ⎡ 2⎤ ⎣x ⎦ In [2]: :input:`(x**2,)` Out[2]: ⎛ 2⎞ ⎝x ⎠ In [3]: :input:`{x**2: 1}` Out[3]: ⎧ 2 ⎫ ⎨x : 1⎬ ⎩ ⎭ so why not? Now let's verify that printing tests pass .. parsed-literal:: $ :input:`py.test sympy/printing/` ============================= test process starts ============================== executable: /usr/bin/python2.5 (2.5.0-final-0) using py lib: /home/kirr/src/tools/py/py-0.9.0/py <rev unknown> sympy/printing/tests/test_gtk.py[1] f sympy/printing/tests/test_latex.py[8] .......f sympy/printing/tests/test_mathml.py[6] .....f sympy/printing/tests/test_pretty.py[10] .........f sympy/printing/tests/test_pretty_unicode.py[10] .......... sympy/printing/tests/test_python.py[6] ...... ============== tests finished: 37 passed, 4 xfail in 0.30 seconds ============= Everything seems to be ok with pprinting evenly heighted sequences. Let's get back to original problem: .. parsed-literal:: In [1]: :input:`class C: pass` ...: In [2]: :input:`C` Out[2]: __main__.C In [3]: :input:`import sympy` In [4]: :input:`sympy.__dict__` (a lot is printed) ok, it works. Let's write tests (this is important) .. parsed-literal:: $ :input:`hqq` # 2.patch_ .. image:: pics/12.png .. _2.patch: spt-patches/2.patch Also, when looking at `_print` function again, I've noticed there are typos in `printer.py` so I've spellchecked the whole file .. parsed-literal:: $ :input:`hqq` # 3.patch_ .. image:: pics/13.png .. _3.patch: spt-patches/3.patch It seems we have done the job now. To ensure everything stays in shape, let's see if all tests pass .. parsed-literal:: $ :input:`./setup.py test` running test ============================= test process starts ============================== executable: /usr/bin/python2.5 (2.5.0-final-0) using py lib: /home/kirr/src/tools/py/py-0.9.0/py <rev unknown> sympy/concrete/tests/test_gosper.py[2] .. sympy/concrete/tests/test_products.py[3] ... sympy/concrete/tests/test_sums_products.py[9] ......fff sympy/core/tests/test_arit.py[35] .................................ff sympy/core/tests/test_assumptions.py[