User Guide


Stable version

The most recommended way of installing gpypi is through portage. Portage will handle all of dependencies and make sure you install stable version.

# sudo emerge -av gpypi

Download and install directly through PyPi:

$ sudo easy_install gpypi


$ sudo pip install gpypi

Development version

$ sudo pip install


$ sudo easy_install

Getting started

gpypi is a command line tool with vision to make Gentoo developers life easier. To create an ebuild and its dependencies:

$ sudo gpypi create --overlay sunrise pylons
* Generating ebuild: Jinja2 2.5
* Your ebuild is here: /usr/local/portage/dev-python/jinja2/jinja2-2.5.ebuild
* Dependency needed: Babel
* Generating ebuild: Babel 0.9.5
* Your ebuild is here: /usr/local/portage/dev-python/babel/babel-0.9.5.ebuild
* Dependency needed: pytz
* Generating ebuild: pytz 2010h
* Your ebuild is here: /usr/local/portage/dev-python/pytz/pytz-2010h.ebuild


Root login must be used for populating overlays and unpacking ebuilds.

Usage should be pretty self explanatory through help:

$ sudo gpypi -h
usage: gpypi [-h] [-v] {create,sync,install,echo} ...

Builds ebuilds from PyPi.

optional arguments:
  -h, --help            show this help message and exit
  -v, --version

    create              Write ebuild and it's dependencies to an overlay
    echo                Echo ebuild to stdout
    install             Install ebuild and it's dependencies
    sync                Populate all packages from pypi into an overlay

and most of the time one will use the gpypi create command:

$ sudo gpypi create -h
usage: gpypi create [-h] [-P PN] [-V PV] [--MY-PV MY_PV] [--MY-PN MY_PN]
                     [--MY-P MY_P] [--homepage HOMEPAGE] [--keywords KEYWORDS]
                     [--license LICENSE] [--description DESCRIPTION]
                     [--long-description LONG_DESCRIPTION] [-u URI]
                     [-i INDEX_URL] [--nocolors] [--config-file CONFIG_FILE]
                     [-q | -d] [-l OVERLAY_NAME] [-o] [--no-deps]
                     [-c CATEGORY] [--metadata-disable]
                     [--metadata-herd METADATA_HERD]
                     [--metadata-maintainer-description METADATA_MAINTAINER_DESCRIPTION]
                     [--metadata-maintainer-email METADATA_MAINTAINER_EMAIL]
                     [--metadata-maintainer-name METADATA_MAINTAINER_NAME]
                     [--echangelog-message ECHANGELOG_MESSAGE]
                     [--repoman-commands REPOMAN_COMMANDS]
                     package name [package version]

Write ebuild and it's dependencies to an overlay

positional arguments:
  package name
  package version

optional arguments:
  -h, --help            show this help message and exit
  -P PN, --PN PN        Specify PN to use when naming ebuild
  -V PV, --PV PV        Specify PV to use when naming ebuild
  --MY-PV MY_PV         Specify MY_PV used in ebuild
  --MY-PN MY_PN         Specify MY_PN used in ebuild
  --MY-P MY_P           Specify MY_P used in ebuild
  --homepage HOMEPAGE   Homepage of the package
  --keywords KEYWORDS   Portage keywords for ebuild masking
  --license LICENSE     Portage license for the ebuild
  --description DESCRIPTION
                        Short description of the package
  --long-description LONG_DESCRIPTION
                        Long description of the package
  -u URI, --uri URI     Specify SRC_URI of the package
  -i INDEX_URL, --index-url INDEX_URL
                        Base URL for PyPi
  --nocolors            Disable colorful output
  --config-file CONFIG_FILE
                        Absolute path to a config file
  -q, --quiet           Show less output.
  -d, --debug           Show debug information.
                        Specify overlay to use by name (stored in
  -o, --overwrite       Overwrite existing ebuild
  --no-deps             Don't create ebuilds for any needed dependencies
  -c CATEGORY, --category CATEGORY
                        Specify portage category to use when creating ebuild

Workflow control:
  Generate metadata, manifest, changelog ...

  --metadata-disable    Disable metadata generation
                        Don't use ECHANGELOG_USER
  --metadata-herd METADATA_HERD
                        Herd for ebuild metadata
  --metadata-maintainer-description METADATA_MAINTAINER_DESCRIPTION
                        Maintainer descriptions for ebuild metadata (comma
  --metadata-maintainer-email METADATA_MAINTAINER_EMAIL
                        Maintainer emails for ebuild metadata (comma
  --metadata-maintainer-name METADATA_MAINTAINER_NAME
                        Maintainer names for ebuild metadata (comma separated)
  --echangelog-disable  Disable echangelog
  --echangelog-message ECHANGELOG_MESSAGE
                        Echangelog commit message
  --repoman-commands REPOMAN_COMMANDS
                        List of repoman commands to issue on each ebuild
                        (separated by space)

Creating ebuild from source of Python package with distutils

gpypi supports not also querying PyPi but also creating an ebuild with help of distutils. Configuration is done when you first run gpypi. cd to your package and just do:

python sdist_ebuild


gpypi offers configuration based on multiple sources. Currently supported sources are: Config.from_pypi(), Config.from_setup_py(), Config.from_argparse() and Config.from_ini().

Configuration API lets you choose what source is used and what priority it has relative to other source providers. Here is a complete list of supported configuration options that Config can provide:

        # 'config_name': ("doc", "type", "default_value"),
        'up_pn': ('Upstream package name', str, ""),
        'up_pv': ('Upstream package version', str, ""),
        'pn': ('Specify PN to use when naming ebuild', str, ""),
        'pv': ('Specify PV to use when naming ebuild', str, ""),
        # TODO: move my_* stuff into config, make [] as default and make sure it handles lists from ini
        'my_pv': ('Specify MY_PV used in ebuild', str, ""),
        'my_pn': ('Specify MY_PN used in ebuild', str, ""),
        'my_p': ('Specify MY_P used in ebuild', str, ""),
        'uri': ('Specify SRC_URI of the package', str, ""),
        'index_url': ('Base URL for PyPi', str, ""),
        'overlay': ('Specify overlay to use by name (stored in $OVERLAY/profiles/repo_name)', str, "local"),
        'overwrite': ('Overwrite existing ebuild', bool, False),
        'no_deps': ("Don't create ebuilds for any needed dependencies", bool, False),
        'category': ("Specify portage category to use when creating ebuild", str, ""),
        'format': ("Format when printing to stdout (use pygments identifier)", str, "none"),
        'command': ("Name of command that was invoked on CLI", str, ""),
        'nocolors': ("Disable colorful output", bool, False),
        'background': ("Background of terminal when using formatting", str, 'dark'),
        #'pretend': ("Print ebuild to stdout, don't write ebuild file, don't download SRC_URI", bool, False),
        'license': ("Portage license for the ebuild", str, ""),
        'keywords': ("PyPI keywords", str, ""),
        # TODO: homepage will be a list
        'homepage': ("Homepage of the package", str, ""),
        'description': ("Short description of the package", str, ""),
        'long_description': ("Long description of the package", str, ""),
        'gentoo_keywords': ("Portage keywords for ebuild masking", str, "~x86"),
        # metadata
        'metadata_disable': ("Disable metadata generation", bool, False),
        'metadata_use_echangelog_user': ("Use ECHANGELOG_USER", bool, False),
        'metadata_herd': ("Herd for ebuild metadata", str, ""),
        'metadata_maintainer_description': ("Maintainer descriptions for ebuild metadata (comma separated)", str, ""),
        'metadata_maintainer_email': ("Maintainer emails for ebuild metadata (comma separated)", str, ""),
        'metadata_maintainer_name': ("Maintainer names for ebuild metadata (comma separated)", str, ""),
        # echangelog
        'echangelog_disable': ("Disable echangelog", bool, False),
        'echangelog_message': ("Echangelog commit message", str, "Initial ebuild generated by g-pypi"),
        # repoman
        'repoman_commands': ("List of repoman commands to issue on each ebuild (separated by space)", str, "manifest"),

Config is basically a dict with few additional classmethods for validation and source processing. Each Config represents configuration values retrieved from specific source.

ConfigManager is a class that handles multiple Config instances. When a value is retrieved from ConfigManager, it is loaded from Config instances located in ConfigManager.configs (dict). Order is specified as use parameter to ConfigManager.

When gpypi is first time used, it will create .ini configuration file at /etc/gpypi. Further usage will load the file with ConfigManager.load_from_ini(). Default configuration file will look something like this:

# main option defaults go here:
# overlay = Personal
# ...

# list the order of configurations
use = argparse ini pypi setup_py
# list of what options will invoke interactive questions when missing
questionnaire_options = overlay

You will notice the use parameter in config_manager section. As already said, it specifies what Config sources are used and in what order. config_manager section is loaded on ConfigManager.load_from_ini() call, creating the ConfigManager instance.

config section is used as ini source provider, populated by Config.from_ini also called in ConfigManager.load_from_ini. Another non-foobared example of configuration file:

format = html
overlay = iElectric
index_url =

use = pypi ini argparse
questionnaire_options = uri category

The last option not yet mentioned is questionnaire_options. The question is, what happens when none of Config sources provide the config value we need? The behavior is specified with questionnaire_options. If configuration option is listed in questionnaire_options, Questionnaire is used to interactively request developer for input through shell. Otherwise, default is used (specified in Config.allowed_options tuple).

Most of ConfigManager.configs are populated in gpypi.cli module.


For example usage of classes, following linked API definition.