Develop Reference

Analyze Python source code using Python and Inspector

I'm developing a static analyzer tool in Python that analyzes Python code for a given .py file and extract the body of classes, methods, etc in order to analyze code metrics (methods size, inheritance, and so on).
I identified the library "Inspect" that seems to suit me. However, I noticed that all the examples provided in the official documentation and external website only use this library by passing concrete instances of objects or functions that they want to analyze; however, I would like to analyze the source code without creating concrete instances of them, to avoid possible compiler errors due to missing library or other factors.
There is possible alternative methods or libraries that I can try to do it?

Can I build and host custom HTML pages at Read the Docs?

My program’s documentation is mainly written in Sphinx, but it also includes two custom HTML pages:
an example report produced by the program;
an extended reference on certain features of the program.
These two HTML files are produced by the program itself, not by Sphinx.
I want to host my docs on Read the Docs, and it would be very convenient for me to build and host the two custom pages, versioned, together with the Sphinx docs.
My program is already installed in the RtD build environment as I have the Install Project option enabled. And since the RtD docs mention writing your own builder, I gather it might be possible to invoke my program from there and have it dump the HTML content in a specific place.
So I really have two questions:
Is this an appropriate use of Read the Docs? I guess it’s not designed to host arbitrary Web pages — but then again, those files are not arbitrary, they are an important part of the docs.
How would I implement it? I’m having a hard time making sense of the RtD API: is this “builder” related in any way to Sphinx builders? how do I hook it up to RtD? perhaps there is an example somewhere?

I achieved the desired result using Sphinx’s html_extra_path feature:
A list of paths that contain extra files [...] They are copied to the output directory.
To generate these files, I haven’t found a better place than right in my conf.py, which seems a bit precarious, but works so far. Of course, Install your project inside a virtualenv needs to be enabled in Read the Docs advanced settings.
Now my custom notices.html and showcase.html are treated just like the .html pages produced by Sphinx itself, with versioning and redirects: http://httpolice.readthedocs.io/page/notices.html

How can I use both Sphinx and Pycco for Python documentation?

I'd like to be able to use Sphinx for the main project documentation, so the docstrings must be in reStructuredText, but I'd also like to generate HTML for reading the inline comments in the style of Pycco, which uses Markdown.
Is there a tool or combination of tools that will allow me to do convert only the docstrings from reStructuredText to Markdown?

The pyment tool can convert docstrings to different formats. You could start with that, and then write a subclass of DocToolsBase to format docstrings the way you like.
See this question What is the standard Python docstring format? for more about python docstring conventions and tooling.

A software called Pandoc may be the right tool. You can see the detail in the page through the hyperlink. I ever wanted to have try of it, but it needs Haskell runtime environment which is a little big, so I gave up.

How to search code snippets

For example I want to know how to use Python pickle serialization & deserialization. Since I've never use it, reading Python official doc would be a great reference, but I prefer some snippets/example codes either has description or not. Like sites for python beginners, someone's blog, or from google codes.
How would you search? Like go to specific sites, or use what keyword. Actually this is a general question not only for Python, but for learning all languages. Thanks.

Google Code Search.
From the FAQ:
We're crawling as much publicly
accessible source code as we can find,
including archives (.tar.gz, .tar.bz2,
.tar, and .zip), CVS repositories and
Subversion repositories.
Sample search: http://www.google.com/codesearch?q=lang%3Apython+%22cpickle%22
The operators are handy:
The lang: operator, which restricts by programming language (e.g., lang:"c++", -lang:java, or lang:^(c|c#|c++)$)
The license: operator, which restricts by software license (e.g., license:apache, -license:gpl, or license:bsd|mit)
The package: operator, which restricts by package URL (e.g., package:"www.kernel.org" or package:.tgz$)
The file: operator, which restricts by filename (e.g., file:include/linux/$ or -file:.cc$)

You can also look at Activestate Python Recipe's:
http://code.activestate.com/recipes/langs/python/
Here's their recipes for Python Pickling:
http://code.activestate.com/search/#q=pickle python
O'Reilly's Python Cookbook is also good. You can read it online with a Safari membership.

There is also Nullege. A search engine especially for Python code.

The Github search is pretty good. It's usually used to search for repository but its search code works well:

In general, Google Code Search is a pretty good place to look for code snippets. To look for Python pickle examples, I'd do a search like
lang:python pickle examples

How to create an internationalized Google App Engine application

I would like to provide my Python GAE website in the user's own language, using only the tools available directly in App Engine. For that, I would like to use GNU gettext files (.po and .mo files).
Has someone successfully combined Python Google App Engine and gettext files? If so, could you please provide the steps you used?
I had started a discussion in GAE's Google group, but haven't been able to extract from it how I'd like to do it: I don't want to add external dependencies, like Babel (suggested in the discussion). I want to use plain vanilla Google App Engine, so no manual update of Django or this kind of stuff.
At first, I will start using the language sent by the browser, so no need to manually force the language by using cookies etc. However, I might add a language changing feature later, once the basic internationalization works.
As a background note to give you more details about what I'm trying to do, I would like to internationalize Issue Tracker Tracker, an open source application I've hosted on Launchpad. I plan to use Launchpad's translation platform (explaining why I'd like to use .mo files). You can have a look at the source code in it's Bazaar branch (sorry no link due to stackoverflow spam prevention limit for new users...)
Thanks for helping me advance on this project!

As my needs were simple, I used a simple hack instead of (unavailable) gettext. I created a file with string translations, translate.py. Approximately like this:
en={}
ru={}
en['default_site_title']=u"Site title in English"
ru['default_site_title']=u"Название сайта по-русски"
Then in the main code I defined a function which returns a dictionary with translations into the most suitable language from the list (the first one to have a translation is used or English):
import translate
def get_messages(languages=[]):
msgs=translate.en
for lang in languages:
if hasattr(translate,lang):
msgs=getattr(translate,lang)
break
return msgs
Usage:
msgs = get_messages(["it","ru","en"])
hi = msgs['hello_message'] % 'yourname'
I also defined a helper function which extracts a list of languages from Accept-Language header.
It's not the most flexible solution, but it doesn't have any external dependencies and works for me (in a toy project). I think translate.py may be generated automatically from gettext files.
In case you want to see more, my actual source is here.

You can use the Django internationalisation tool, like explained here.
They are also saying that there is no easy way to do this.
I hope that helps you :)