DEMO: http://hg.python-works.com

TRACKER: http://bitbucket.org/marcinkuzminski/hg-app/issues

Since last time hg-app got:

• Full permissions per repository system.
• Yui float graphs
• New gui
• Database based settings and hooks
• Huge number of bugfixes.

Below few screenshots of new hg-app gui.

It’s available on PyPi as “vcs”, so you can install it using PIP or EASY_INSTALL.

Simply run to download and install it.

easy_install vcs
pip install vcs

Lukasz made a nice documentation, and quick starts available here http://packages.python.org/vcs/

The vcs API:

Features

• Common API for SCM backends (mercurial is the first and only one available right now)
• Fetching repositories data lazily (performance and easy of use)
• Simple caching mechanism so we don’t hit repo too often (so a refresh on a 2000 commit repo wont kill  the cpu)

Incoming

• Django app for mercurial hgserve replacement – this is probably going to be a part of the vcs library
• Pylons app for mercurial replacement – this is my little project which i finished roughly in 70% of functionality that hgwebdir does.
• Command line client

Few things are worth mentioning.
The key point of vcs to have the same api for various SCM-s so mercurial,git,subversion(maybe others) will have
a same way for data access,objects structures and so on. Imagine how fast and simple you could extend an web app which uses
mercurial as a SCM to GIT, simply replace the repo path to git and all should work. Of Course there are some differences between git and mercurial
that could be handled in the same maner, and this is also simply handled by a private methods, specific for a SCM.

This is of course an open source project and any contributors are always welcomed.

Yolk is “Command-line tool querying PyPI and Python packages installed on your system”
Yolk can list your current environment packages including some useful additional information about them like ‘active’ or
‘non-active’ packages, it can list packages that could be upgrade (simply yolk -U).

Before I’d had to manually search my python path and copy/paste each package to easy_install -U, what was quite annoying.
Now in few seconds i can get the list of upgradable packages and upgrade them.

Another great tool in yolk is PyPI quering. For example:

$ yolk -F Paste
     Download source tarball for latest version of Paste to your current directory

$ yolk -F Paste -T svn
     Do a subversion checkout for Paste to a directory named Paste_svn in your current directory.

$ yolk -L 2
     Show list of CheeseShop releases in the last two hours

So you can always get the news from PyPI and maybe find some interesting packages.
If your using easy_install i’m quite sure you will love yolk.

It doesn’t matter if you are creating project for your company or you plan to release it as an open source – by providing documentation you make life easier for other contributors and end-users, of course. And if you know how to write restructuredText documents then you already own necessary skills to create documentation lighting fast!

Prepare!

First of all, you would need to have Distutils and Sphinx installed. You can install it using one of the Python package management tools, in example easy_install would do the job. I prefer to use pip:

pip install distutils
pip install sphinx

Simply use any project you’d like to create documentation for, I would use django-richtemplates. Create a new directory for your documentation and run sphinx-quickstart command:

hg clone https://bitbucket.org/lukaszb/django-richtemplates/ django-richtemplates-temp
cd django-richtemplates-temp
sphinx-quickstart

Just answer some questions – they are very straightforward. You should probably turn autodoc option on.
Sphinx would create some directories for internal usage and static content storage (_build, _static and _templates), configuration file (conf.py) and index file (index.html). Ok, enough of this crap, lets create our first documentation page!

First page

Create new file, lets call it installation.rst and write the document itself:

.. _installation:

============
Installation
============

Fake installation for `django-richtemplates`_ project.

Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod
tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam,
quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo
consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse
cillum dolore eu fugiat nulla pariatur.

.. note::
   Yeah, this would be a note.
   Very simple, indeed.

Some more crap
--------------

If you would like to highlight a code snippet, it is as easy as::

   from mycompany.auth import AuthenticationBackend

   class MyClass(object):
       """
       Docstring.
       """
       def __init__(self, *args, **kwargs):
           """
           Some *business* logic.
           """
           pass
       def authenticate(self, username, password):
           """
           External authentication process.
           """
           auth = AuthenticationBackend(username, password)
           return auth.is_authenticated()

Or choose language explicit:

.. code-block:: bash

   cd django-richtemplates
   sudo python setup.py install

Yeah, `restructuredText `_ is great!
And easy, too.

External-internal hyperlinks
----------------------------

You may also use ``sphinx`` features, like linking to other *documents*, like
this: go to :ref:`configuration`.

.. _django-richtemplates: http://bitbucket.org/lukaszb/django-richtemplates/

This is standard restructured text document. The only sphinx specific parts are first line (need to add relation with file itself – this is needed for table of contents generation) and reference to other file (which is done with ref:`configuration`). Yup, we haven’t created configuration.rst file, yet. So do this now, and paste following:

.. _configuration:

=========================
Configuring richtemplates
=========================

I hope you have already read chapter :ref:`installation`.

Lorem ipsum!
------------

Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod
tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam,
quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo
consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse
cillum dolore eu fugiat nulla pariatur.

Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod
tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam,
quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo
consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse
cillum dolore eu fugiat nulla pariatur.

Don’t forget about the main page!

I once hoped that the first page (namely index.rst) is generated automatically, yet, I was wrong. But in order
to supply needed data for sphinx generator you have to make very simple changes to the index.rst. Just add
:glob: option to the toctree directive. Finally, mark that all (*) restructuredText documents should
be used.

.. django-richtemplates documentation master file, created by
   sphinx-quickstart on Sat Feb 20 21:42:53 2010.
   You can adapt this file completely to your liking, but it should at least
   contain the root `toctree` directive.

Welcome to django-richtemplates's documentation!
================================================

Contents:

.. toctree::
   :maxdepth: 2
   :glob:

   *

Indices and tables
==================

* :ref:`genindex`
* :ref:`modindex`
* :ref:`search`

Now in mydocs directory run

make html

and open file located at mydocs/_build/html/index.html. You should see your documentation!

Final words

Ok, this was very simple and the effect is – for such a little work done – quite amazing if you’d ask me.
However, we still haven’t used autodoc Sphinx’s extension. Let’s do that now – create new file
api.rst and paste whats below:

.. _api:

===
API
===

You can find some basic API information here.

Forms API
---------

In this section we cover some basics about the `django-richtemplates`'s forms
API.

.. automodule:: richtemplates.forms
   :members:

.. _django-richtemplates: http://bitbucket.org/lukaszb/django-richtemplates/

Again, run make command and see your documentation. Ok, so where is your API, you ask? Well, if you look at the output
of make html command you’d see that there was a warning – richtemplates.forms couldn’t be found.
Which is completely correct, as Sphinx doesn’t try to guess where your modules are, you have to configure it by yourself.
Change sys.path by uncommenting existing line and change it to this:

sys.path.append(os.path.abspath('..'))

If you are not sure why why put .. there, it’s simple – Sphinx would go a one directory up (..) and try to find richtemplates there. Try to build your documentation now. Warning again? Yeah, Sphinx now complains about not
having DJANGO_SETTINGS_MODULE which is, again, totally correct. As importing richtemplates won’t
raise exception, but trying to get deeper into the module (richtemplates.forms) would be impossible without
being within Django context (same would happen if you try to run python interpreter and run from django import forms).
So add this line into your conf.py file:

os.environ['DJANGO_SETTINGS_MODULE'] = 'django.conf.global_settings'

More information about autodoc extension could be found here.

Hope this would help anyone trying to start with his/her own documentation :)
If you have any suggestions – let me know.

Take care and make documentation, not war.

Since IntelliJ is a really the best Java IDE out there, i presume their next product
dedicated to python will be worth switching.

It’s still in preview but as for now it provides:

• Coding Assistance
• Project Code Navigation
• Google App Engine Support
• Code Analysis
• Python Refactoring
• Web Development with Django (some really nice ones)
• debugger
• Integrated unit tests
• Version control integration

I’d tested under linux, seems to be a littler slower than my eclipse home brew version, but I’d expect the final version faster. It has few nice features, easy configuration, code completion are doing fine.
You can grab a free 45 day copy from here.

I’ll for sure fallow this product development. Stay posted for more !

I used the babel extractor recommended by pylons and that went really smooth.

My application have a language selector available anytime from menu.
I saw that even this switch worked very well for mako templates and string inside controllers,
it did not work when displaying my custom messages that i over rid in validators
and also did not work in my own custom validators that inherit from FancyValidator.
So i started to investigate this.

The first problem of not translating custom error messages in the regular formencode validators was easily being fixed by using lazy_ugettex method.

def _(s):
    #fix for translation error messages
    return lazy_ugettext(s)

This method allowed me to use lazy_ugettext to translate.
So now when in the validators your translating a string using _(‘this string is for translate’) method it’s actually wrapper for lazy_ugettext function.
Lazy translation is when you translate a string when it is accessed, not when the _() or other functions are called.

The second problem of translating custom error messages in your own validator was a bigger problem

I was looking for a solution for some time, and found a nice trick. You have to use your own
state_obj with static _() function. As example below for custom validation function.

class ValidLoginNames(formencode.validators.FancyValidator):

    messages = {'invalid_name':_('you cannot use %(username)s as login')}

    def validate_python(self, value, state):
        banned_names = ['admin', 'administrator', 'root']
        if value in banned_names:
            raise formencode.Invalid(self.message('invalid_name', state = State_obj, username = value), value, state)

#this is needed to translate the messages using _()
class State_obj(object):
    _ = staticmethod(_)

Those two trick now let’s you translate custom validators without a problem.

Sorry for the problems.

Be sure to check them out.

An example of such a function:

def read_large_file(filename, mode = 'rs', size = '1024'):
    '''
    A lazy generator functions that reads a file with a given chunk of data
    USAGE:
    for data_chunk in read_large_file('/tmp/huge.file','rb',10240):
        print data_chunk
    @param filename: a filename
    @param mode: read mode
    @param size: size to read at one iteration
    '''
    with open(filename, mode) as f:
        while 1:
            data = f.read(size)
            if not data:
                break
            yield data

Remember that with statement is supported out of the box from python 2.6 in python
2.5 you have to do

from __future__ import with_statement

before using it. If you have troubles using with statement i recommend reading
this link