rjgtoys.projects: A simple wrapper for setuptools¶
Provides an alternative to the setuptools.setup()
function
that defines a Python project.
This package is very specific to how I like to build projects, and I doubt it will be of much use to anyone else.
I’m offering a brief writeup here because you might come across it if you look at my other projects, so it needs an explanation.
In order to be able to build other rjgtoys projects you’ll probably need to install this one first.
Once you’ve done that, the setup.py from other rjgtoys projects should work more or less as you expect.
Getting it¶
Method 1: Install from PyPi¶
By the time you read this, rjgtoys-projects
should be available on PyPi:
pip install --user rjgtoys-projects
Method 2: Get the source code¶
To get the source code:
git clone https://github.com/bobgautier/rjgtoys-projects.git
Then make the package available for your Python:
cd rjgtoys-projects
python ./setup.py develop --user
If you are using a virtualenv, you should omit the --user
option used
in these examples.
Starting a new project: rjgtoys-new¶
This command line tool simplifies starting a new project; it creates an empty project tree based on a few parameters you provide either in a configuration file or on the command line.
Command line options¶
Use --help
to get a list of options:
$ rjgtoys-new --help
usage: Build a new rjgtoys project [-h] [--name NAME] [--id IDENT] --title TEXT [--template PATH] [--update] [--config PATH] [--dry-run]
optional arguments:
-h, --help show this help message and exit
--name NAME Public name of the project, for docs etc.
--id IDENT Internal name of the project, for directories etc.
--title TEXT One-line title for the project
--template PATH Template name or path (default: rjgtoys)
--update Update an existing project (default: False)
--config PATH Configuration to use (default: $HOME/.config/rjgtoys/projects/projects.conf)
--dry-run, -n Don't generate anything, just validate (default: False)
--id | A short name for the project, used for directories, files, and so on. This name will be used for the main package source directory of the project. |
--name | A ‘documentation name’ for the project; usually very similar or identical to the id, but sometimes capitalised, or slightly modified in some other way. For example, rjgtoys-xc (id: xc) has the name XC because I think that looks better in documentation. |
--title | A one-line description of the project. |
--template | The name of a template set to use for the project. This is a path,
and relative paths are interpreted relative to a If you want to experiment with this, be prepared to learn about Cookiecutter. |
--update | If this option is used, rjgtoys-new will update an existing directory
(and might therefore lose you some work). |
--config | Specifies a configuration file from which to get further parameters for the project. The configuration file is described below. |
--dry-run | If used, no files or directories will be created or updated. |
The project tree is created (or updated) in a directory named with the id you specified.
Configuration file¶
#
# Example prototype projects.conf
#
# Make an accurate version of this file and put it in
#
# ~/.config/rjgtoys/projects/projects.conf
#
project:
family: rjgtoys
copyright:
year: 2020
author:
fullname: "Robert J. Gautier"
email: "bob.gautier@gmail.com"
github:
base: https://github.com/bobgautier/
The file is YAML.
The parameters are as follows. For brevity I’ve used dotted names here, to indicate the paths through the nested mappings that are expected in the configuration file.
- project.family
Name of the group to which the project belongs. The default is rjgtoys, resulting in projects called
rjgtoys-ID
.If you start using this tool yourself, please use a different family name; I chose rjgtoys in the hope of avoiding a clash with someone else.
- copyright.year
- The year to include in copyright notices.
- author.fullname
- Full name of the author.
- author.email
- Email address of author.
- github.base
- Base URL for github repos; project repositories will be expected to be ‘under’ this URL.
Using setup.py¶
My version of setup()
adds some new commands, and customises
some existing ones.
Extended ‘test’ command¶
The ‘test’ command uses pytest and coverage, so that an HTML coverage report is generated.
You will find the coverage report at htmlcov/index.html
in your project tree.
The command goes to some trouble to enumerate all the Python source code files in your project tree, so that they are included in the coverage report even if they are not referenced by any tests. This is to avoid making coverage look good when only a few modules have any tests at all.
Using setuptools to run tests is now deprecated, so eventually I will have to find a different way to do this.
‘lint’ command¶
The ‘lint’ command runs pylint.
The configuration is embedded in rjgtoys-projects (so that it’s standard for all my projects).
The report is left in the project directory, in pylint.out
.
‘jenkins’ command¶
The ‘jenkins’ command can create a Jenkins job to build the project.
This command is just an old experimental proof-of-concept.
Credits¶
The templating is all done with Cookiecutter.