generator-python-lib
Release 5.0.13

Generator for bootstrapping a Python library.

Keywords: generator, python, yeoman, yeoman-generator
License: Apache-2.0
Install: npm install generator-python-lib@5.0.13

Documentation

@hutson/generator-python-library

Generator for bootstrapping a Python library.

generator-python-library scaffolds a basic Python 3 library, including build and test support, and example source files, using your responses to a series of command line prompts.

Features
Installation
Usage
- Setting up Documentation
- Adding Dependencies
Composability
Options
Debugging
Node Support Policy
Contributing

Features

[x] Bootstrap Python 3 compatible library.
[x] Bootstrap support for the Pipenv package manager.
[x] Bootstrap support for writing tests using Python's built-in unittest framework.
[x] Bootstrap Tox configuration file tox.ini for testing against multiple Python interpreters.
[x] Bootstrap Pylint configuration file .pylintrc for checking code quality.
[x] Bootstrap Git configuration files, .gitattributes and .gitignore.
[x] Bootstrap CONTRIBUTING.md file.
[x] Bootstrap README.md file.
[x] Bootstrap .coveragerc file for code coverage support.

Installation

To install generator-python-library please run the following command:

yarn global add @hutson/generator-python-library

Make sure you have the Yeoman CLI tool, yo, installed globally. You can install Yeoman via the following command:

yarn global add yo

You will also need to have Python installed on your system to work with your scaffolded Python library.

Usage

Create a new directory to host your project and navigate into it:

mkdir my-new-library && cd my-new-library

Then run the generator to scaffold your project:

yo @hutson/python-library

You will be prompted for input that will be used to bootstrap your project. Keep in mind that your responses, and the resulting file contents, can be changed at a later date by re-running the generator.

Once your Python library has been scaffolded you will need to install Pipenv, the preferred package manager:

pip install --no-cache-dir pipenv==2018.11.26

Next, create a virtual environment to house all the development tools needed by your project:

pipenv install --dev --python python

To run a tool inside of the virtual environment:

pipenv run [TOOL]

For example, to check for code quality, run the following:

pipenv run python setup.py lint

To run the project's unit tests against the version of Python installed inside of the virtual environment:

pipenv run python setup.py test

To run your tests against multiple Python interpreters, and check for code quality, we use a tool called tox. Tox allows you to run your library's unit tests against all versions of Python installed on your system as configured in the tox.ini file.

pipenv run tox

To generate a code coverage report run the following:

pipenv run python setup.py coverage

A full line-by-line coverage report can be viewed by navigating into the coverage/ directory and opening index.html in your browser.

For a full list of tasks available from your project's setup.py file, run the following:

pipenv run python setup.py --help-commands

Setting up Documentation

The development dependencies of the newly scaffolded Python library includes Sphinx, a great tool for building documentation.

Though generator-python-library includes Sphinx as a development dependency, we do not actually setup a documentation folder, or scaffold documentation files. Sphinx already has an excellent tool for setting up a project's documentation, and we defer to that tool, and the workflow it supports.

To get started with setting up your project's documentation please go through Sphinx's tutorial. You may skip the Install Sphinx section as you've already installed Sphinx by installing the scaffolded project's development dependencies.

If you run the setup script, sphinx-quickstart, in the root of your project, you'll probably want to set the Root path for the documentation to docs.

Regarding the questions asked by sphinx-quickstart, I believe selecting y, or yes, is a good idea for the following:

doctest - Testing doctest blocks will ensure the code examples embedded within your documentation actually work.
coverage - Having Sphinx provide coverage feedback will ensure you're building out documentation for the entire public API of your project.
viewcode - Linking to the source code will allow consumers of your library to dive into the code to better understand its mechanics.

Adding Dependencies

Please read through the Basic Usage of Pipenv to better understand how dependencies should be managed.

When declaring a runtime dependency, the dependency should also be included in the install_requires list of your project's setup.py file. Furthermore, the dependency should include upper and lower version bounds (though not a specific version).

Composability

generator-python-library may be integrated into other Yeoman generators through Yeoman's composability feature.

First off you will need to add generator-python-library to your generator's dependencies:

yarn add @hutson/generator-python-library

To invoke generator-python-library add the following code to any method in your generator:

this.composeWith(`@hutson/python-library`, {
    options: {}
});

If passing options to the generator:

this.composeWith(`@hutson/python-library`, {
    options: {
        'skip-welcome-message': true
    }
});

Options

generator-python-library supports several options; their default values are listed below.

Options may be provided on the command line, such as passing --projectName=my-project-name when calling generator-python-library directly, or via the options argument passed to composeWith.

When the value for an option is fetched from the working directory's .yo-rc.json file, or passed as a command line argument, this yeoman generator will not prompt you for the value.

skip-welcome-message

Default: UNDEFINED

Should the generator's welcome message be skipped (suppressed)?