Welcome | Get started | Dive | Contribute | Topics | Reference | Changes | More

How Lino applications use setup.py

This document is obsolete after #5484 (Migrate from setup.py to pyproject.toml).

It describes our trick for keeping the metadata about a Python package in a single place. It does not depend on Lino and we recommend it for any Python project which contains a package.

The classical layout is to store the setup information directly in the setup.py file of your project. The problem with this layout is that the setup.py file is not available at runtime.

For example the version number. You need it of course in the setup.py, but there are quite some projects that want to show somehow their version. So they need it at runtime as well. And that number can change quickly and can be critical. You don’t want to store it in two different places.

Is there a way to have setup information both in a central place and* accessible at runtime?

It is an old problem, and e.g. Single-sourcing the package version describes a series of answers.

Our solution

To solve this problem, we store the setup information in a separate file, which we usually name setup_info.py and which we load from both our setup.py and our packages’s main __init__.py file. The setup.py loads it using the exec() function while the packages’s main __init__.py file can simply import it.

That’s why the setup.py of a package “xxyyzz” contains just this:

from setuptools import setup
fn = 'xxyyzz/setup_info.py')
with open(fn, "rb") as fd:
    exec(compile(fd.read(), fn, 'exec'))
if __name__ == '__main__':
    setup(**SETUP_INFO)

And the __init__.py file of the main module contains this:

from os.path import join, dirname
from setup_info import SETUP_INFO
__version__ = SETUP_INFO.get('version')

Usage examples:

>> from lino import SETUP_INFO
>> print(SETUP_INFO['description'])
A framework for writing desktop-like sustainably free web applications using Django and ExtJS or React

>> from lino_xl import SETUP_INFO
>> print(SETUP_INFO['description'])
The Lino Extensions Library

Related files

These are the files we are talking about here.

setup.py

A file named setup.py is part of the minimal structure of every Python project. It is in the root directory of a project and contains information about the project, e.g. the version number or the dependencies (i.e. which other Python packages must be installed when using your package). The information in this file is used for running test suites, installing the project in different environments, etc…

setup_info.py

The file that actually contains the information for Python’s setup.py script. It is loaded (or imported) from both the setup.py and the packages’s main __init__.py file and usually defines a global variable SETUP_INFO, a dict of keyword arguments to be passed to the setup() function. It is located in the directory that contains the main package of your project. E.g. for the Lino Extensions Library project it is in lino_xl/setup_info.py. the main package of a project is specified in the tasks.py.

MANIFEST.in

TODO

test_packages.py

A file in the test suite of a repository that runs run_packages_test.

Setup information

The setup() function has a lot of keyword parameters, which are documented elsewhere.

install_requires

See http://python-packaging.readthedocs.io/en/latest/dependencies.html

tests_require

See http://python-packaging.readthedocs.io/en/latest/dependencies.html

description

A terse plain-text description of the package. Usually a single sentence and no period at the end.

For applications known by getlino this is also listed on List of known Lino applications.

long_description

A longer description to be published on PyPI.

May contain reStructuredText formatting, but no Sphinx-specific additions.

How to suggest changes to a README file

The long_description in the setup_info.py file is also used by inv bd as the source text for generating the project’s README.rst.

We assume that you have installed a development environment as explained in Install your Lino developer environment.

Open the setup_info.py file of your project and find the long_description.

Edit its content.

Run inv bd in the root directory of the project. This will ask you:

Overwrite /path/to/my/project/README.rst [Y,n]?

Hit ENTER.

Open the README.rst file and check that it contains your changes.

Submit a pull request with the two modified files setup_info.py and README.rst.