Narcoleptic's Patch Mangler
    Share your code. npm Orgs help your team discover, share, and reuse code. Create a free org »

    generator-python-libpublic

    generator-python-lib

    build status codecov

    Generator for bootstrapping a Python library.

    generator-python-lib 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.

    Table of Contents

    Features

    • Bootstrap Python 3 compatible library.
    • Bootstrap support for writing tests using Python's built-in unittest framework.
    • Bootstrap Tox configuration file tox.ini to support executing tests against multiple Python interpretors.
    • Bootstrap Pylint configuration file .pylintrc for checking code quality.
    • Bootstrap Git configuration files, .gitattributes and .gitignore.
    • Bootstrap CONTRIBUTING.md file.
    • Bootstrap README.md file.
    • Bootstrap Coverage.py for code coverage support.

    Installation

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

    yarn global add generator-python-lib

    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 pip and virtualenv installed to work with your scaffolded Python library.

    Usage

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

    • Linux: mkdir my-new-lib && cd $_
    • Windows CMD or PowerShell: mkdir my-new-lib && cd my-new-lib

    Then run the generator:

    yo python-lib

    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 create a virtual environment:

    virtualenv --python=python3 venv

    The value python3 passed to --python is the name of the Python interpreter you want to install into your virtual environment. Further calls to python while within your virtual environment will use that Python interpreter.

    Next you'll need to activate the virtual environment by sourcing the activate script created within the virtual environment directory.

    • Linux: source ./venv/bin/activate
    • Windows CMD or PowerShell: venv\Scripts\activate

    Note: If you encounter any issues sourcing the activate script, please read the virtualenv setup documentation.

    Now your shell environment is configured to expose all tools and libraries installed within the virtual environment. With the virtual environment activated you can install your library's required development tools by running:

    pip install -r requirements-dev.txt

    Once your development dependencies are install you can run your library's unit tests:

    python setup.py test

    Unit tests are only executed once, and only against the version of Python that was installed within your virtual environment.

    To run your tests against multiple Python interpreters we included a development dependency called tox which allows you to run your library's unit tests against all versions of Python installed on your system. You can run tox by just running the tool itself:

    tox

    tox has been configured, through the tox.ini file, to re-create a virtual environment for every Python version under test, during every execution. This ensures that the virtual environment represents exactly what you specify as your project's dependencies.

    For example, if you had a library, such as requests installed in your virtual environment, but removed it from your project's setup.py file, then the next time you run your tests, requests, along with the testing environment, will be cleaned up. Now, if you start using requests in your project again, but fail to list it in the install_requires section of setup.py, your tests will fail; since the newly created virtual environment won't contain requests.

    To generate a coverage report, run the following:

    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 through setup.py 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-lib 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 install_requires vs Requirements files section of the Python Packaging User Guide to better understand how dependencies should be managed.

    When declaring a dependency the dependency should 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).

    Your project's requirements.txt file is scaffolded such that pip installing requirements.txt via pip install -r requirements.txt will install your project's dependencies declared in setup.py.

    Composability

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

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

    yarn add generator-python-lib

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

    this.composeWith(`python-lib`, {
        options: {}
    });

    If passing options to the generator:

    this.composeWith(`python-lib`, {
        options: {
            'skip-welcome-message': true
        }
    });

    Options

    generator-python-lib 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-lib 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)?

    projectName

    Default: [Name of project folder]

    Used as the module name for your Python library,

    fullName

    Default: Previously defined value in .yo-rc.json file or UNDEFINED

    Your full name.

    email

    Default: Previously defined value in .yo-rc.json file or UNDEFINED

    Contact e-mail for those trying to reach you as the author of the library.

    gitlabName

    Default: Previously defined value in .yo-rc.json file or UNDEFINED

    Your GitLab username.

    ciProvider

    Default: Previously defined value in .yo-rc.json file or UNDEFINED

    Continuous Integration provider, such as Travis CI (option value of Travis CI).

    Debugging

    To assist users of generator-python-lib with debugging the behavior of this module we use the debug utility package to print information about the publish process to the console. To enable debug message printing, the environment variable DEBUG, which is the variable used by the debug package, must be set to a value configured by the package containing the debug messages to be printed.

    To print debug messages on a unix system set the environment variable DEBUG with the name of this package prior to executing generator-python-lib:

    DEBUG=generator-python-lib generator-python-lib

    On the Windows command line you may do:

    set DEBUG=generator-python-lib
    generator-python-lib

    Node Support Policy

    We only support Long-Term Support versions of Node.

    We specifically limit our support to LTS versions of Node, not because this package won't work on other versions, but because we have a limited amount of time, and supporting LTS offers the greatest return on that investment.

    It's possible this package will work correctly on newer versions of Node. It may even be possible to use this package on older versions of Node, though that's more unlikely as we'll make every effort to take advantage of features available in the oldest LTS version we support.

    As each Node LTS version reaches its end-of-life we will remove that version from the node engines property of our package's package.json file. Removing a Node version is considered a breaking change and will entail the publishing of a new major version of this package. We will not accept any requests to support an end-of-life version of Node. Any merge requests or issues supporting an end-of-life version of Node will be closed.

    We will accept code that allows this package to run on newer, non-LTS, versions of Node. Furthermore, we will attempt to ensure our own changes work on the latest version of Node. To help in that commitment, our continuous integration setup runs against all LTS versions of Node in addition the most recent Node release; called current.

    JavaScript package managers should allow you to install this package with any version of Node, with, at most, a warning if your version of Node does not fall within the range specified by our node engines property. If you encounter issues installing this package, please report the issue to your package manager.

    Contributing

    Please read our contributing guide on how you can help improve this project.

    install

    npm i generator-python-lib

    Downloadslast 7 days

    341

    version

    4.0.42

    license

    Apache-2.0

    homepage

    gitlab.com

    repository

    gitlab.com

    last publish

    collaborators

    • avatar