Setup¶
Custom setup.py
Commands¶
flutils offers the ability to quickly add additional
setup.py
custom commands to a Python project.
Requirements¶
Custom Setup Commands can be used in Python projects that are using setuptools with a
setup.cfg
configuration file.Setup Commands requires that the
setup.py
andsetup.cfg
files exist in the root directory of a typical Python project structure:my_project/ │ ├── docs/ │ ├── doc1.rst │ └── doc2.rst │ ├── my_project/ │ ├── __init__.py │ ├── module1.py │ └── module2.py │ ├── setup.cfg ├── setup.py └── tests/ ├── test1.py └── test2.pyTo use Custom Setup Commands, the
setup.cfg
file must have, at least, the following defined:[metadata] name == my_project
Custom Command Definitions¶
The actual command definitions can exist in
setup.cfg
and/orsetup_commands.cfg
. If thesetup_commands.cfg
file exists then the command definitions from in this file will be used; and, command definitions insetup.cfg
are ignored.The general idea is to have
setup_commands.cfg
ignored by version control, allowing developers customize command definitions to their specific needs. While command definitions needed for deployment, testing etc can be kept in version control.Each individual Custom-Setup-Command definition starts with a section header of:
[setup.command.<name-of-custom-setup-command>]Underneath the section header the following options can be used:
description = <text>
: A short description about the custom setup command. This is displayed withsetup.py --help-commands
command = <text>
: The command line command or commands to execute when thesetup.py
custom command is called.
commands = <text>
: The command line command or commands to execute when thesetup.py
custom command is called. If bothcommand
andcommands
exist, the value ofcommand
will be executed first.
name = <text>
: This option can override the<name-of-custom-setup-command>
set in the section header.The following string interpolation variables can be used on all but the
name
option.
{name}
: the name of the project as set in the[metadata]
sectionname
option.
{setup_dir}
: The full path to the directory that contains thesetup.py
file.
{home}
: The full path to the user’s home directory.
Example setup.cfg
¶
The following example of
setup.cfg
contains the definitions for thesetup.py lint
andsetup.py lint-all
commands:[metadata] name = my_project [setup.command.lint] description = Lint the {name} project files command = pylint --rcfile={setup_dir}/.pylintrc {setup_dir}/{name} [setup.command.lint_all] name = lint-all description = Lint the {name} project and test files commands = pylint --rcfile={setup_dir}/.pylintrc {setup_dir}/{name} pylint --rcfile={setup_dir}/.pylintrc {setup_dir}/tests
Implementation¶
The final step of using Custom Setup Commands is to prepare the commands and tell setuptools.
add_setup_cfg_commands
(setup_kwargs, setup_dir=None)[source]¶Add additional custom
setup.py
commands that are defined insetup.cfg
.
- Parameters
setup_kwargs (dict) – A dictionary holding the setuptools.setup keyword arguments. (see example below).
setup_dir (
str
orPath
, optional) – The root directory of the project. (e.g. the directory that contains thesetup.py
file). Defaults to:None
which will try to determine the directory using the call stack.- Return type
Example
Use in
setup.py
like the following:#!/usr/bin/env python import os from setuptools import setup from flutils.setuputils import add_setup_cfg_commands setup_kwargs = {} setup_dir = os.path.dirname(os.path.realpath(__file__)) add_setup_cfg_commands(setup_kwargs, setup_dir=setup_dir) setup(**setup_kwargs)