20160811 (Thursday, 11 August 2016)

I made an upgrade on The Lino framework because at least the Lino Voga online demo was broken.

I worked on the Dive into Lino because I realized (thanks to James and Grigorij) that after “Getting started” and “Your first Lino application” I need to insert a new section “Working with others”.

How to find the source code from dotted notation

Here is a newbie question which surprised me, I wasn’t aware that this might be a problem, I needed James to stumble over it.

Some days ago I gave him the following hint for fixing #1127:

You’ll need to move some code from the get_used_libs() method in lino.core.site.Site to lino_welfare.projects.std.settings.Site

He then asked:

Where can I find lino_welfare.projects.std.settings.Site?

Answer 1

Imagine that I would have written my hint in this blog, using Sphinx markup to create underlying links:

You’ll need to move some code from the get_used_libs method in lino.core.site.Site to lino_welfare.projects.std.settings.Site.

You can now click on these links. Clicking on a link leads you to the API documentation page, more precisely to the section of that page which shows the docstring of the class or method I am taking about.

But how to find the source code? Note that every API documentation page has, somewhere near the top, in a paragraph on its own, the following sentence:

(This module’s source code is available _here_.)

Clicking on the word _here_ leads you to a place on GitHub which should show you the source file.

Answer 2

But you can do all this without clicking and without internet connection, if you have the source code.

For example lino_welfare.projects.std.settings.Site.

The part before the first dot is lino_welfare. This is the top-level name of a python package. It is the pythonic name of Lino Welfare, which is published on PyPI under https://pypi.python.org/pypi/lino-welfare and which you cloned from GitHub. Your copy of the source code should be in ~/repositories/welfare. The structure of that directory is a normal Python project, it contains (among others):

docs/
lino_welfare/
tests/
setup.py
README.rst

A special challenge with the name lino_welfare.projects.std.settings.Site is that the corresponding source code is defined either in a file lino_welfare/projects/std/settings.py or in a file lino_welfare/projects/std/settings/__init__.py. Only one of them can exist (Python would get confused if they would exist both).