ionelmc / cookiecutter-pylibrary Goto Github PK

View Code? Open in Web Editor NEW

1.2K 23.0 206.0 1.2 MB

Enhanced cookiecutter template for Python libraries.

License: BSD 2-Clause "Simplified" License

Python 91.48% C 8.12% Cython 0.40%

python cookiecutter-template template cookiecutter

cookiecutter-pylibrary's Introduction

cookiecutter-pylibrary

Cookiecutter template for a Python library.

Notes:

This is largely designed to address this blog post about packaging python libraries.
- ... and it will save you from packaging pitfalls.
There's a bare library using this template (if you're curious about the final result): https://github.com/ionelmc/python-nameless.
If you have a web application (not a library) you might want to take a look at django-docker.

Table of Contents

Features

This is an "all inclusive" sort of template.

Choice of various licenses.
Tox for managing test environments for Python 2.7, 3.7+, PyPy etc.
Pytest or Nose for testing Python 2.7, 3.7+, PyPy etc.
Optional support for creating a tests matrix out of dependencies and python versions.
Travis-CI and AppVeyor for continuous testing.
Coveralls or Codecov for coverage tracking (using Tox).
Documentation with Sphinx, ready for ReadTheDocs.
Configurations for:
- isort
- bumpversion (bump2version required)
Support for C extensions (including coverage measurement for the C code). See c_extension_support.
Packaging and code quality checks. This template comes with a tox environment (check) that will:
- Check if your README.rst is valid.
- Check if the MANIFEST.in has any issues.

Requirements

Projects using this template have these minimal dependencies:

Cookiecutter - just for creating the project
Tox - for running the tests
Setuptools - for building the package, wheels etc. Now-days Setuptools is widely available, it shouldn't pose a problem :)

To get quickly started on a new system, just install setuptools and then install pip. That's the bare minimum to required install Tox and Cookiecutter. To install them, just run this in your shell or command prompt:

pip install tox cookiecutter

Usage and options

This template is more involved than the regular cookiecutter-pypackage.

First generate your project:

cookiecutter gh:ionelmc/cookiecutter-pylibrary

You will be asked for these fields:

Note

Fields that work together usually use the same prefix. If you answer "no" on the first one then the rest won't have any effect so just ignore them. Maybe in the future cookiecutter will allow option hiding or something like a wizard.

Field	Default	Description
`full_name`	"Ionel Cristian Maries"	Main author of this library or application (used in `AUTHORS.rst` and `setup.py`). Can be set in your `~/.cookiecutterrc` config file.
`email`	"[email protected]"	Contact email of the author (used in `AUTHORS.rst` and `setup.py`). Can be set in your `~/.cookiecutterrc` config file.
`website`	"https://blog.ionelmc.ro"	Website of the author (used in `AUTHORS.rst`). Can be set in your `~/.cookiecutterrc` config file.
`repo_username`	"ionelmc"	GitHub user name of this project (used for GitHub link). Can be set in your `~/.cookiecutterrc` config file.
`project_name`	"Nameless"	Verbose project name, used in headings (docs, readme, etc).
`repo_hosting_domain`	"github.com"	Use `"no"` for no hosting (various links will disappear). You can also use `"gitlab.com"` and such but various things will be broken (like Travis configuration).
`repo_name`	"python-nameless"	Repository name on GitHub (and project's root directory name).
`package_name`	"nameless"	Python package name (whatever you would import).
`distribution_name`	"nameless"	PyPI distribution name (what you would `pip install`).
`module_name`	"core"	This template assumes there's going to be an "implementation" module inside your package.
`project_short_description`	"An example package [...]"	One line description of the project (used in `README.rst` and `setup.py`).
`release_date`	"today"	Release date of the project (ISO 8601 format) default to today (used in `CHANGELOG.rst`).
`year`	"now"	Copyright year (used in Sphinx `conf.py`).
`version`	"0.1.0"	Release version (see `.bumpversion.cfg` and in Sphinx `conf.py`).
`c_extension_support`	"no"	Support C extensions (will slightly change the outputted `setup.py`). Available options: `"yes"` - to generate a Python C extension `"cffi"` - to generate CFFI bindings against a C library `"cython"` - to generate a Cython extension
`c_extension_optional`	"no"	Make C extensions optional (will allow your package to install even if extensions can't be compiled)
`test_matrix_separate_coverage`	"no"	Enable this to have a separate env for measuring coverage. Indicated if you want to run doctests or collect tests from `src` with pytest.
`setup_py_uses_setuptools_scm`	"no"	Enables the use of setuptools-scm. You can continue using bumpversion with this enabled.
`tests_inside_package`	"no"	Collect tests that are inside the package (in other works, tests that are installed with the package). The outside of package tests directory will still exist and be collected.
`command_line_interface`	"plain"	Option to enable a CLI (a bin/executable file). Available options: `plain` - a very simple command. `argparse` - a command implemented with `argparse`. `click` - a command implemented with click - which you can use to build more complex commands. `no` - no CLI at all.
`command_line_interface_bin_name`	"nameless"	Name of the CLI bin/executable file (set the console script name in `setup.py`).
`license`	"BSD license"	License to use. Available options: BSD license MIT license ISC license Apache Software License 2.0 What license to pick? https://choosealicense.com/
`coveralls`	"no"	Enable pushing coverage data to Coveralls and add badge in `README.rst`.
`codecov`	"yes"	Enable pushing coverage data to Codecov and add badge in `README.rst`. Note: Doesn't support pushing C extension coverage yet.
`scrutinizer`	"no"	Add a Scrutinizer badge in `README.rst`.
`codacy`	"no"	Add a Codacy badge in `README.rst`. Note: After importing the project in Codacy, find the hexadecimal project ID from settings and replace it in badge URL
`codeclimate`	"no"	Add a CodeClimate badge in `README.rst`.
`sphinx_docs`	"yes"	Have Sphinx documentation.
`sphinx_theme`	"sphinx-rtd-theme"	What Sphinx theme to use. Suggested alternative: sphinx-py3doc-enhanced-theme for a responsive theme based on the Python 3 documentation.
`sphinx_doctest`	"no"	Set to `"yes"` if you want to enable doctesting in the docs environment. Works best with `test_matrix_separate_coverage == 'no'`. Read more about doctest support in Sphinx.
`sphinx_docs_hosting`	"repo_name.readthedocs.io"	Leave as default if your documentation will be hosted on readthedocs. If your documentation will be hosted elsewhere (such as GitHub Pages or GitLab Pages), enter the top-level URL.
`pypi_badge`	"yes"	By default, this will insert links to your project's page on PyPI.org. Note that if your package is not (yet) on PyPI, this will cause tox -e docs to fail. If you choose "no", then these links will not be created.
`pypi_disable_upload`	"no"	If you specifically want to be sure your package will never be accidentally uploaded to PyPI, you can pick "yes".

Developing the project

To run all the tests, just run:

tox

To see all the tox environments:

tox -l

To only build the docs:

tox -e docs

To build and verify that the built package is proper and other code QA checks:

tox -e check

Releasing the project

Before releasing your package on PyPI you should have all the tox environments passing.

Version management

This template provides a basic bumpversion configuration. It's as simple as running:

bumpversion patch to increase version from 1.0.0 to 1.0.1.
bumpversion minor to increase version from 1.0.0 to 1.1.0.
bumpversion major to increase version from 1.0.0 to 2.0.0.

You should read Semantic Versioning 2.0.0 before bumping versions.

Building and uploading

Before building dists make sure you got a clean build area:

rm -rf build
rm -rf src/*.egg-info

Note:

Dirty build or egg-info dirs can cause problems: missing or stale files in the resulting dist or strange and confusing errors. Avoid having them around.

Then you should check that you got no packaging issues:

tox -e check

And then you can build the sdist, and if possible, the bdist_wheel too:

python setup.py clean --all sdist bdist_wheel

To make a release of the project on PyPI, assuming you got some distributions in dist/, the most simple usage is:

twine upload --skip-existing dist/*.whl dist/*.gz dist/*.zip

In ZSH you can use this to upload everything in dist/ that ain't a linux-specific wheel (you may need setopt extended_glob):

twine upload --skip-existing dist/*.(whl|gz|zip)~dist/*linux*.whl

For making and uploading manylinux1 wheels you can use this contraption:

docker run --rm -itv $(pwd):/code quay.io/pypa/manylinux1_x86_64 bash -c 'set -eux; cd code; rm -rf wheelhouse; for variant in /opt/python/*; do rm -rf dist build *.egg-info && $variant/bin/python setup.py clean --all bdist_wheel; auditwheel repair dist/*.whl; done; rm -rf dist build *.egg-info'
twine upload --skip-existing wheelhouse/*.whl
docker run --rm -itv $(pwd):/code quay.io/pypa/manylinux1_i686 bash -c 'set -eux; cd code; rm -rf wheelhouse; for variant in /opt/python/*; do rm -rf dist build *.egg-info && $variant/bin/python setup.py clean --all bdist_wheel; auditwheel repair dist/*.whl; done; rm -rf dist build *.egg-info'
twine upload --skip-existing wheelhouse/*.whl

Note:

twine is a tool that you can use to securely upload your releases to PyPI. You can still use the old python setup.py register sdist bdist_wheel upload but it's not very secure - your PyPI password will be sent over plaintext.

Changelog

See CHANGELOG.rst.

Questions & answers

There's no Makefile?

Sorry, no Makefile yet. The Tox environments stand for whatever you'd have in a Makefile.

Why does tox.ini have a passenv = *?

Tox 2.0 changes the way it runs subprocesses - it no longer passes all the environment variables by default. This causes all sorts of problems if you want to run/use any of these with Tox: SSH Agents, Browsers (for Selenium), Appengine SDK, VC Compiler and so on.

cookiecutter-pylibrary errs on the side of convenience here. You can always remove passenv = * if you like the strictness.

Why is the version stored in several files (pkg/__init__.py, setup.py, docs/conf.py)?

We cannot use a metadata/version file¹ because this template is to be used with both distributions of packages (dirs with __init__.py) and modules (simple .py files that go straight in site-packages). There's no good place for that extra file if you're distributing modules.

But this isn't so bad - bumpversion manages the version string quite neatly.

Not Exactly What You Want?

No way, this is the best. 😜

If you have criticism or suggestions please open up an Issue or Pull Request.

Example, an __about__.py file.↩

cookiecutter-pylibrary's People

Contributors

Stargazers

Watchers

Forkers

stefankjartansson ahurriyetoglu fmarczin git2samus cacconelabyale midnighter cowanml svetlyak40wt mvmocanu vladiibine eyepea orientalperil paregorios yakazimir kaidokert bogdan-pr django-stables matias-pizarro xguse agherwig koodaamo tomschr abusalimov djiit brbsix pawamoy bear luzfcb taleinat tboquet simonbiggs gangatn tantale fladi nkabir lorengordon vauxoo dragon788 nateyoder mpicard praveen-symphony twik benbaror rfleschenberg thecontinium hiway catlee spiette dectinc andrewpong snakescott techdragon insertjokehere riccardomurri bopo bosr yoelk ericmharris jakirkham hsiaoyi0504 nyimbi leezu laurii yngtodd admjls mberz meeas egrunzke cmarquardt draperjames jpvlsmv georgerichardson plstcharles nestauk achennu gpfreitas natemarks jab pcrespov chanjunweimy rcuza mouchtaris adamboche janluke dhetting bagerard ninpo csci-e-29-dev koraykinik mjcarleb sedelmeyer jorgepiloto tcarmet jtrakk ahmed-masud dhuckins andrew-vant rickwxc dhannasch tabulon-ext

cookiecutter-pylibrary's Issues

code coverage not counted when using subprocess.Popen()

Try as I might (and I've tried a few things for a few hours now), code executed in subprocess.Popen calls isn't included in the coverage report. Not on Travis/Coveralls, and not locally. Do you have this problem? Do you have any idea why?

My repository (see the develop branch): https://github.com/cmeeren/latexdiffcite
Tests in question: in tests/test_latexdiffcite.py, functions test_run_module (should test the final line in __main__.py) and test_main (should test a lot of the otherwise untested stuff in latexdiffcite.py).

This may not be due to cookiecutter-pylibrary, but then again it might, and if it boils down to some configuration, then I assume you want to have it working. :)

Commenting out python versions breaks tox

Contents of setup.cfg:

...
python_versions =
    2.7
    #3.3
    #3.4
    #3.5
    #pypy
...

Contents of tox.ini:

[testenv:#3.3-cover]
basepython = {env:TOXPYTHON:python#3.3}
setenv =
    {[testenv]setenv}
    WITH_COVERAGE=yes
    SETUPPY_CFLAGS=-coverage
usedevelop = true
commands =
    python setup.py clean --all build_ext --force --inplace
    {posargs:py.test --cov --cov-report=term-missing -vv}
deps =
    {[testenv]deps}
    pytest-cov

Of course the easy fix it to delete python versions and not comment them out.

FR: Allow license selection

I'd like to be able to pick e.g. Apache-2 instead of BSD. Would a PR for this be welcome?

Have a flag to use setuptools_scm

Hmmm

Windows 10, Anaconda, --> tox doesn't work

I'm on windows 10, 64-bit. I have a somewhat old Anaconda with base python version 3.6.0 installed. I have tried to use this template with my root conda env and with a more recent 3.6.2 python env. Even just running through all the default options, running tox does not run. Any suggestion?

C:\Users\<username>\Projects\TEST\python-nameless> tox
GLOB sdist-make: C:\Users\<username>\Projects\TEST\python-nameless\setup.py
clean create: C:\Users\<username>\Projects\TEST\python-nameless\.tox\clean
ERROR: InterpreterNotFound: python3
check create: C:\Users\<username>\Projects\TEST\python-nameless\.tox\check
ERROR: InterpreterNotFound: python3
py27 create: C:\Users\<username>\Projects\TEST\python-nameless\.tox\py27
ERROR: InterpreterNotFound: python2.7
py33 create: C:\Users\<username>\Projects\TEST\python-nameless\.tox\py33
ERROR: InterpreterNotFound: python3.3
py34 create: C:\Users\<username>\Projects\TEST\python-nameless\.tox\py34
ERROR: InterpreterNotFound: python3.4
py35 create: C:\Users\<username>\Projects\TEST\python-nameless\.tox\py35
ERROR: InterpreterNotFound: python3.5
py36 create: C:\Users\<username>\Projects\TEST\python-nameless\.tox\py36
ERROR: InterpreterNotFound: python3.6
pypy create: C:\Users\<username>\Projects\TEST\python-nameless\.tox\pypy
ERROR: InterpreterNotFound: pypy
report create: C:\Users\<username>\Projects\TEST\python-nameless\.tox\report
ERROR: InterpreterNotFound: python3
docs create: C:\Users\<username>\Projects\TEST\python-nameless\.tox\docs
ERROR: InterpreterNotFound: python2.7
___________________________________ summary ___________________________________
ERROR:   clean: InterpreterNotFound: python3
ERROR:   check: InterpreterNotFound: python3
ERROR:   py27: InterpreterNotFound: python2.7
ERROR:   py33: InterpreterNotFound: python3.3
ERROR:   py34: InterpreterNotFound: python3.4
ERROR:   py35: InterpreterNotFound: python3.5
ERROR:   py36: InterpreterNotFound: python3.6
ERROR:   pypy: InterpreterNotFound: pypy
ERROR:   report: InterpreterNotFound: python3
ERROR:   docs: InterpreterNotFound: python2.7

bootstrap env is missing basepython

The generated tox.ini doesn't have basepython set for the bootstrap environment, so tox -e bootstrap doesn't work as documented. An easy workaround is to just run python ci/bootstrap.py directly.

Steps to reproduce:

mkvirtualenv test1
pip install tox cookiecutter
curl https://raw.githubusercontent.com/rfleschenberg/rf-django-misc/master/.cookiecutterrc > testconfig
cookiecutter --config-file=testconfig gh:ionelmc/cookiecutter-pylibrary
Accept defaults for all prompts
cd rf-django-misc
tox -e bootstrap

GLOB sdist-make: /tmp/rf-django-misc/setup.py
bootstrap recreate: /tmp/rf-django-misc/.tox/bootstrap
ERROR: InterpreterNotFound: 
_______________________________________________________ summary _______________________________________________________
ERROR:   bootstrap: InterpreterNotFound:

No such file or directory: 'ci/appveyor-bootstrap.ps1'

Traceback (most recent call last):
File "/var/folders/5q/24r8h7nn2cn0_vbz9x454xfr0000gp/T/tmp42pow7.py", line 9, in
os.unlink(join('ci', 'appveyor-bootstrap.ps1'))
OSError: [Errno 2] No such file or directory: 'ci/appveyor-bootstrap.ps1'

Should the package name be prefixed with "python-" in the repository name?

Is it suggested in any relevant document? I don't think it's common practice.

nocov environments fails if distribution_name ends with .py

Hi there,

I was just trying this cookiecutter template and I can't get the "nocov" environments working.

From a freshly generated projet, every time I try a tox or just a tox -e py2.7-nocov command, I get the following message :

pypy-nocov create: /home/jtanay/dev/mylib/.tox/pypy-nocov
pypy-nocov installdeps: pytest, pytest-travis-fold
pypy-nocov inst: /home/jtanay/dev/mylib/.tox/dist/mylib-0.3.0.zip
pypy-nocov installed: You are using pip version 6.0.2, however version 7.1.2 is available.,You should consider upgrading via the 'pip install --upgrade pip' command.,mylib==0.3.0,cffi==1.1.0,click==6.2,greenlet==0.4.7,py==1.4.31,pytest==2.8.5,pytest-travis-fold==1.2.0,readline==6.2.4.1
pypy-nocov runtests: PYTHONHASHSEED='1942620883'
pypy-nocov runtests: commands[0] | py.test -vv --ignore=src
=============================================================================================== test session starts ===============================================================================================
platform linux2 -- Python 2.7.9[pypy-2.6.0-final], pytest-2.8.5, py-1.4.31, pluggy-0.3.1 -- /home/jtanay/dev/mylib/.tox/pypy-nocov/bin/pypy
cachedir: .cache
rootdir: /home/jtanay/dev/mylib, inifile: setup.cfg
plugins: travis-fold-1.2.0
collected 13 items / 2 errors 

AUTHORS.rst SKIPPED
CHANGELOG.rst SKIPPED
CONTRIBUTING.rst SKIPPED
README.rst SKIPPED
docs/authors.rst SKIPPED
docs/changelog.rst SKIPPED
docs/contributing.rst SKIPPED
docs/index.rst SKIPPED
docs/installation.rst SKIPPED
docs/readme.rst SKIPPED
docs/usage.rst SKIPPED
docs/reference/avid.rst SKIPPED
docs/reference/index.rst SKIPPED

===================================================================================================== ERRORS ======================================================================================================
_______________________________________________________________________________________ ERROR collecting tests/test_mylib _______________________________________________________________________________________
tests/test_mylib:4: in <module>
    from avid.__main__ import main
E   ImportError: No module named avid.__main__
_______________________________________________________________________________________ ERROR collecting tests/test_mylib _______________________________________________________________________________________
tests/test_mylib:4: in <module>
    from avid.__main__ import main
E   ImportError: No module named avid.__main__
============================================================================================= short test summary info =============================================================================================
ERROR tests/test_mylib
ERROR tests/test_mylib
SKIP [13] /home/jtanay/dev/mylib/.tox/pypy-nocov/site-packages/_pytest/doctest.py:165: all tests skipped by +SKIP option
======================================================================================= 13 skipped, 2 error in 0.17 seconds =======================================================================================
ERROR: InvocationError: '/home/jtanay/dev/mylib/.tox/pypy-nocov/bin/py.test -vv --ignore=src'

However, when I try this with the example python-nameless lib, it runs smoothly without this error.

i'm running tox from python 2.7 on a Ubuntu 15.04. Here is my cookiecutterrc :

default_context:

    appveyor:                  'yes'
    c_extension_optional:      'no'
    c_extension_support:       'no'
    codacy:                    'no'
    codeclimate:               'no'
    codecov:                   'yes'
    command_line_interface:    'click'
    coveralls:                 'no'
    distribution_name:         'mylib'
    email:                     '[email protected]'
    full_name:                 'Julien Tanay'
    github_username:           'Djiit'
    landscape:                 'no'
    package_name:              'mylib'
    project_name:              'mylib'
    project_short_description: 'mylib'
    release_date:              'today'
    repo_name:                 'mylib'
    requiresio:                'yes'
    scrutinizer:               'no'
    sphinx_theme:              'readthedocs'
    test_matrix_configurator:  'no'
    test_runner:               'pytest'
    travis:                    'yes'
    version:                   '0.3.0'
    website:                   'http://example.com'
    year:                      'now'

Thanks for your help

bootstrap.py generate a wrong matrix in .travis.yml if used with python 3.5

run with python3.5:

  matrix:
    - TOXENV=check
    - TOXENV=docs

    - TOXENV=b'clean',codecov

    - TOXENV=b'check',codecov

    - TOXENV=b'py27-django18',codecov

    - TOXENV=b'py27-django19',codecov

    - TOXENV=b'py27-djangomaster',codecov

    - TOXENV=b'py34-django18',codecov

    - TOXENV=b'py34-django19',codecov

    - TOXENV=b'py34-djangomaster',codecov

    - TOXENV=b'py35-django18',codecov

    - TOXENV=b'py35-django19',codecov

    - TOXENV=b'py35-djangomaster',codecov

    - TOXENV=b'pypy-django18',codecov

    - TOXENV=b'pypy-django19',codecov

    - TOXENV=b'pypy-djangomaster',codecov

    - TOXENV=b'report',codecov

    - TOXENV=b'docs',codecov

run with python2.7:

  matrix:
    - TOXENV=check
    - TOXENV=docs

    - TOXENV=py27-django18,codecov

    - TOXENV=py27-django19,codecov

    - TOXENV=py27-djangomaster,codecov

    - TOXENV=py34-django18,codecov

    - TOXENV=py34-django19,codecov

    - TOXENV=py34-djangomaster,codecov

    - TOXENV=py35-django18,codecov

    - TOXENV=py35-django19,codecov

    - TOXENV=py35-djangomaster,codecov

    - TOXENV=pypy-django18,codecov

    - TOXENV=pypy-django19,codecov

    - TOXENV=pypy-djangomaster,codecov

py_modules

I'm trying to wrap my head around the changes necessary to setup.py when using a src directory... and shouldn't py_modules be:

py_modules=[splitext(basename(i))[0] for i in glob.glob("src/{{cookiecutter.package_name}}/*.py")]

(the middle directory is missing)

Purpose of WITH_COVERAGE

Thanks for putting together such a robust template! Big fan of it

I couldn't find any references as to what that env var purpose is. The closest I found was NOSE using a similar variable.

Whats the benefit of running the tests with and without coverage? On all my projects I always run them with coverage on.

Thanks again,

Deprecation warning when using `setup.py check` through tox

Hi, first of all thanks for the great project!
When running tox from my bootstrapped project, I have the following warning that gets printed:
warning: Check: This command has been deprecated. Use twine check instead: https://packaging.python.org/guides/making-a-pypi-friendly-readme#validating-restructuredtext-markup

Its not a big deal but I thought it was worth to be fixed, I'll push a PR shortly

Question: where is the variable TOXPYTHON used?

I generated a project with this cookie cutter (thanks!) and I'm trying to get a handle on how everything is set up.

One thing that I'm having trouble finding documentation on is the use of the environment variable TOXPYTHON. Where is this variable used and why is it important?

If anyone could point me towards some information I would be very grateful.

Adding test dependencies

I have two packages, one pytest plugin and scipy, that I need in the test environments. I don't want them to be part of the test matrix. So where is the best place to add them? I could edit the tox.ini but that seems silly since that file is automatically generated. So is there a better place for it?

Allow no Creation of Documentation (docs dir)

Great project! 👍

When you are asked by cookiecutter, you can only decide which Sphinx theme you would like to use.

However, some projects create there documentation without Sphinx or use different tools. For that reason, it would be nice to have a use_doc entry in cookiecutter.json (or something similar). If yes (default) is selected, the usual process is executed. With no, no docs directory is created and any Sphinx theme is skipped.

Does that make sense? 😃

unable to load another local module in cli

Hi, I'm facing a problem, and I came to your project to see if I found a solution but it also happens with your suggested structure.

Without it installed, If we create more files inside src/nameless/ like src/nameless/test.py containing:

def foo():
    return 'bar'

and import it in src/nameless/cli.py like:

import click

from nameless.test import foo
print(foo())


@click.command()
@click.argument('names', nargs=-1)
def main(names):
    click.echo(repr(names))

main()

When executing it like: python cli.py it returns:

Traceback (most recent call last):
  File "cli.py", line 19, in <module>
    from nameless.test import foo
ModuleNotFoundError: No module named 'nameless'

also, It works importing it like:

from test import foo
print(foo())

but If I do that, the command nameless stop working:

$ nameless

Traceback (most recent call last):
  File "/tmp/nameless-virt/bin/nameless", line 11, in <module>
    load_entry_point('nameless==0.1.0', 'console_scripts', 'nameless')()
  File "/tmp/nameless-virt/lib/python3.6/site-packages/pkg_resources/__init__.py", line 564, in load_entry_point
    return get_distribution(dist).load_entry_point(group, name)
  File "/tmp/nameless-virt/lib/python3.6/site-packages/pkg_resources/__init__.py", line 2662, in load_entry_point
    return ep.load()
  File "/tmp/nameless-virt/lib/python3.6/site-packages/pkg_resources/__init__.py", line 2316, in load
    return self.resolve()
  File "/tmp/nameless-virt/lib/python3.6/site-packages/pkg_resources/__init__.py", line 2322, in resolve
    module = __import__(self.module_name, fromlist=['__name__'], level=0)
  File "/tmp/nameless-virt/lib/python3.6/site-packages/nameless-0.1.0-py3.6.egg/nameless/cli.py", line 19, in <module>
    from test import foo
ImportError: cannot import name 'foo'

is there a way to make it work (without install the package) by only running python cli.py and if installed, it also works with the command nameless? I'm not able to manage both, I tried using some relative imports cli but it shows other types of problems too.

Thx.

read function doesn't close the file?

Hi thanks for the cookiecuter template! I was looking at the setup.py and the read function it looks like the file handle is not closed after reading in the file?

shouldn't the with statement be used to make sure the file handle gets closed?

with io.open(
    join(dirname(__file__), *names), encoding=kwargs.get('encoding', 'utf8')) as f:
    return f.read()

Blank line at end of cli.py

I've been trying to set this up on Windows and making some progress after I actually installed the vcpython27 package to be able to compile extensions. Oddly enough I already had Visual Studio Community 2015 but it was having issues with it not being able to find/use the proper compiler.

After I got all those issues sorted out, I'm getting failures on flake8 about a blank line at the end of cli.py, and some documentation failures with sphinx-build, but those I expect because I'm using it for a non-Github project in a private repo.

Delayed Compilation of Extensions

Hi, I've been playing around with Cython and C extensions a lot lately and one issue that bugs me again and again is availability of Cython and inclusion of headers. Your package does a good job of checking for Cython and falling back to pre-compiled *.c sources when it's not found but one thing that's still missing is delayed building of extensions that, for example, depend on the numpy headers which still need to be installed.

matplotlib has a solution here and I was wondering if that's interesting to you? If yes, I can work on a pull request that would add this feature.

Typo in ci/templates/tox.ini?

When I try to run tox with tox -e bootstrap, I get the following output:

$ tox -e bootstrap
GLOB sdist-make: /local/doc/docmanager/setup.py
bootstrap installed: Jinja2==2.8,MarkupSafe==0.23,matrix==1.3.1,wheel==0.24.0
bootstrap runtests: PYTHONHASHSEED='411462886'
bootstrap runtests: commands[0] | python bootstrap.py
.tox/bootstrap/bin/python: can't open file 'bootstrap.py': [Errno 2] No such file or directory
ERROR: InvocationError: '/local/doc/docmanager/.tox/bootstrap/bin/python bootstrap.py'
______________ summary______________
ERROR:   bootstrap: commands failed

I think the ci/templates/tox.ini file contains a typo:

https://github.com/ionelmc/cookiecutter-pylibrary/blob/master/%7B%7Bcookiecutter.repo_name%7D%7D/ci/templates/tox.ini#L62

[testenv:bootstrap]
# Pruned some lines
commands =
    python bootstrap.py

should be this (see the ci/ before bootstrap.py):

[testenv:bootstrap]
# Pruned some lines
commands =
    python ci/bootstrap.py

tox -e configure: unknown environment 'configure'

When I run tox -e configure, I get ERROR: unknown environment 'configure'.

README: running "twine register" is no longer necessary

As written here: https://github.com/pypa/twine#twine-register

WARNING: The register command is no longer necessary if you are uploading to pypi.org. As such, it is no longer supported in Warehouse (the new PyPI software running on pypi.org). However, you may need this if you are using a different package index.

You may consider to update the README.

Configurable nosetests support

I want to contribute a nosetests support. What is the best way to make choice between py.test and nose configurable?

readthedocs strips dots from repo_name

Hi,

When using ReadTheDocs with a repo_name containing dots ("."), it strips them i.e. : "nameless.py" gives "namelesspy.readthedocs.org" and "namelesspy.rtfd.org"

ReadTheDocs link is then broken in README.rst. We should strip dots from readthedocs links; but I'm not sure how to do it...

Thx

Tox overwrites user's .cookiecutterrc

Running Tox overwrites the users .cookiecutterrc file.
Should be fixable with some configuration changes.

Support for GitHub enterprise URLs

Great project!

I am using this cookiecutter for some projects at Georgia Tech, most of which may eventually migrate to GitHub proper. In the meantime, I have to go through a laborious process to change all the links to point at the enterprise url. In this particular case, github.com gets changed to github.gatech.edu to convert over. Is this something would be easy to change?

I don't have any experience writing cookiecutter templates, but I suppose I could try.

Please, add a CHANGELOG.md for the project

Please, add a CHANGELOG.md, so that anybody could track how does cookiecutter-pylibrary evolve (or even subscribe to its release notes at http://allmychanges.com).

Python versions controls

First off, this is INCREDIBLE!

Okay, gushing aside, what would be really nice is the ability to specify which versions of Python you want bootstrap.py to manage. I know I can hand-craft that in the configuration, but I always forget to do that.

Again, this is amazing. Wow.

Error when testing with Python 3.5

When I test using Python 3.5, I get the following error almost right off the bat, no matter if my "active" Python interpreted when running tox is 2.7 or 3.5:


C:\Users\Christer\code\python\aacgmv2>tox -re 3.5
3.5 create: C:\Users\Christer\code\python\aacgmv2\.tox\3.5
ERROR: invocation failed (exit code 1), logfile: C:\Users\Christer\code\python\aacgmv2\.tox\3.5\log\3.5-0.log
ERROR: actionid: 3.5
msg: getenv
cmdargs: ['C:\\Anaconda\\python.exe', '-m', 'virtualenv', '--python', 'c:\\python35\\python.exe', '3.5']
env: *snip*

Running virtualenv with interpreter c:\python35\python.exe                                                                                                          
Traceback (most recent call last):                                                                                                                                  
  File "C:\Anaconda\lib\site-packages\enum\__init__.py", line 371, in __getattr__                                                                                   
    return cls._member_map_[name]                                                                                                                                   
KeyError: '_convert'                                                                                                                                                

During handling of the above exception, another exception occurred:                                                                                                 

Traceback (most recent call last):                                                                                                                                  
  File "C:\Anaconda\lib\site-packages\virtualenv.py", line 23, in <module>                                                                                          
    import subprocess                                                                                                                                               
  File "c:\python35\lib\subprocess.py", line 364, in <module>                                                                                                       
    import signal                                                                                                                                                   
  File "c:\python35\lib\signal.py", line 8, in <module>                                                                                                             
    _IntEnum._convert(                                                                                                                                              
  File "C:\Anaconda\lib\site-packages\enum\__init__.py", line 373, in __getattr__                                                                                   
    raise AttributeError(name)                                                                                                                                      
AttributeError: _convert                                                                                                                                            

ERROR: InvocationError: C:\Anaconda\python.exe -m virtualenv --python c:\python35\python.exe 3.5 (see C:\Users\Christer\code\python\aacgmv2\.tox\3.5\log\3.5-0.log)

Multiprocessing fix on Travis

On this page I came across the following which is meant to fix multiprocessing on Travis:

before_install:
  - sudo rm -rf /dev/shm
  - sudo ln -s /run/shm /dev/shm

I haven't tested multiprocessing on Travis, so I don't know if it's actually broken or if the fix works, but I thought I'd let you know.

Allow docopts in command_line_interface

It would be nice to allow docopts, another popular command line parsing library in command_line_interface.

The user could then select between plain, click, argparse, no, and doctops.

Use pip cache on AppVeyor and Travis

Speed up pip install is a really great idea. Caches are supported on both Travis and AppVeyor. It would be great if you could enable caching so it works locally and at Travis and AppVeyor!

(I'm developing an extension that depends on numpy, which takes quite a while to compile each time...)

Make use of tox dimensionality

See https://testrun.org/tox/latest/config-v2.html

It says on the top that it's a draft, but then it says later on that 1.4 is the "current configuration", and my installed tox at least is version 2.0. So if the features described on that page have been implemented, then it might be worth it to make use of them. (I have no idea what kind of changes this would entail for this project).

PyPI download count doesn't work

I think PyPI actually doesn't expose this information anymore. We should just remove the corresponding shields.io badge, I think.

Why 32 bit only on AppVeyor, not Travis?

I see that AppVeypor is set up with both 32 and 64 bit Python versions. I can't see that Travis is set up with 32 bit (it uses 64 bit as default, as far as I know). Is there a good reason for this?

Why not skip_install = true in environment "docs"?

Why is not skip_install = true in the tox environment docs? It works fine when I add it.

The cookiecutter project does not offer options for non-open source projects

The project offers awesome options for open source projects that are completely free such as appveyor, travis ci, coveralls, and codedov but it does not offer offer alternatives for projects that are in-house or that are not open source. It would be nice to know some of the free alternatives that are out there for non-open source projects.

Mention and link to semantic versioning

I, in my blissful ignorance, see no reason why anyone creating a new project using this template has any reason NOT to use semantic versioning. The website says:

If all of this sounds desirable, all you need to do to start using Semantic Versioning is to declare that you are doing so and then follow the rules. Link to this website from your README so others know the rules and can benefit from them.

I propose that you add something to that effect to the readme and link to the website.

spell testenv fails: "The 'enchant' C library was not found"

tox -e spell fails with the following error: Could not import extension sphinxcontrib.spelling (exception: The 'enchant' C library was not found. Please install it via your OS package manager, or use a pre-built binary wheel from PyPI.)

Full log:

$ tox -e spell
spell create: C:\Users\Christer\code\python\latexdiffcite\.tox\spell
spell installdeps: -rC:\Users\Christer\code\python\latexdiffcite/docs/requirements.txt, sphinxcontrib-spelling, pyenchant
spell develop-inst: C:\Users\Christer\code\python\latexdiffcite
spell installed: alabaster==0.7.4,Babel==1.3,colorama==0.3.3,docutils==0.12,Jinja2==2.7.3,latexdiffcite==0.9.0,MarkupSafe==0.23,pockets==0.2.4,pyenchant==1.6.6,Pygments==2.0.2,pytz==2015.4,six==1.9.0,snowballstemmer==1.2.0,Sphinx==1.3.1,sphinx-rtd-theme==0.1.8,sphinxcontrib-napoleon==0.3.6,sphinxcontrib-spelling==2.1.1,wheel==0.24.0
spell runtests: PYTHONHASHSEED='242'
spell runtests: commands[0] | sphinx-build -b spelling docs dist/docs
Running Sphinx v1.3.1

Extension error:
Could not import extension sphinxcontrib.spelling (exception: The 'enchant' C library was not found. Please install it via your OS package manager, or use a pre-built binary wheel from PyPI.)
ERROR: InvocationError: 'C:\\Users\\Christer\\code\\python\\latexdiffcite\\.tox\\spell\\Scripts\\sphinx-build.EXE -b spelling docs dist/docs'
___________________________________ summary ___________________________________
ERROR:   spell: commands failed

Excerpt from my tox.ini:

[testenv:spell]
setenv =
    SPELLCHECK = 1
commands =
    sphinx-build -b spelling docs dist/docs
usedevelop = true
deps =
    -r{toxinidir}/docs/requirements.txt
    sphinxcontrib-spelling
    pyenchant

Using Windows 7 64 bit, launching tox from Python 3.4.

travis yml formatting issue

It looks like there is some issue in the travis.yml template

https://gist.github.com/frostidaho/828e018131a6f8e72a24fa2182e99d95

Docs fail to build under Sphinx 1.4

I decided to give this template a try today! Coincidentally, Sphinx 1.4 was also released today. Sphinx 1.4 introduces some incompatible changes, including removal of the hard dependency on sphinx_rtd_theme. This is currently causing the build to fail:

$ tox -e docs
GLOB sdist-make: /Users/sean/tmp/cookie-sphinx/python-nameless/setup.py
docs create: /Users/sean/tmp/cookie-sphinx/python-nameless/.tox/docs
docs installdeps: -r/Users/sean/tmp/cookie-sphinx/python-nameless/docs/requirements.txt
docs inst: /Users/sean/tmp/cookie-sphinx/python-nameless/.tox/dist/nameless-0.1.0.zip
docs installed: alabaster==0.7.7,Babel==2.2.0,docutils==0.12,imagesize==0.7.0,Jinja2==2.8,MarkupSafe==0.23,nameless==0.1.0,Pygments==2.1.3,pytz==2016.3,six==1.10.0,snowballstemmer==1.2.1,Sphinx==1.4
docs runtests: PYTHONHASHSEED='3980784878'
docs runtests: commands[0] | sphinx-build -E -b html docs dist/docs
Running Sphinx v1.4
making output directory...

Exception occurred:
  File "conf.py", line 41, in <module>
ImportError: No module named sphinx_rtd_theme
The full traceback has been saved in /var/folders/mj/nmpw6v8s15z_cj39dmv0fk9m0000gn/T/sphinx-err-_FW4dq.log, if you want to report the issue to the developers.
Please also report this if it was a user error, so that a better error message can be provided next time.
A bug report can be filed in the tracker at <https://github.com/sphinx-doc/sphinx/issues>. Thanks!
ERROR: InvocationError: '/Users/sean/tmp/cookie-sphinx/python-nameless/.tox/docs/bin/sphinx-build -E -b html docs dist/docs'
___________________________________ summary ____________________________________
ERROR:   docs: commands failed

I chose all of the defaults in creating the sample project.

Environment:

OS: OS X 10.10 Yosemite
Python: tox run by CPython 3.5.1, docs built by CPython 2.7.11
I use pyenv to manage my Pythons.

As reported by Python:
3.5.1:

platform.platform(): Darwin-14.5.0-x86_64-i386-64bit
platform.mac_ver(): ('10.10.5', ('', '', ''), 'x86_64')
platform.python_compiler(): GCC 4.2.1 Compatible Apple LLVM 7.0.2 (clang-700.1.81)
platform.python_implementation(): CPython
platform.python_version(): 3.5.1
platform.architecture(): ('64bit', '')

2.7.11:

platform.platform(): Darwin-14.5.0-x86_64-i386-64bit
platform.mac_ver(): ('10.10.5', ('', '', ''), 'x86_64')
platform.python_compiler(): GCC 4.2.1 Compatible Apple LLVM 7.0.2 (clang-700.1.81)
platform.python_implementation(): CPython
platform.python_version(): 2.7.11
platform.architecture(): ('64bit', '')

Thanks for creating this template!

keywords in setup.py

I couldn't find relevant documentation on it anywhere, so I am not sure whether keywords in setup.py can be a list of strings or just a string separated with strings.

In all packages I have seen, it can only be the latter, though the template seems to suggest that it ought to be a list of strings.

Could you please link me to documentation where a list of strings is declared as a valid value for keywords?

Thanks!

local building of docs and dependencies

My current project has one dependency which I mention in install_requires in setup.py. I also have the package available in my virtual environment and thus sphinx-build runs just fine. tox -e docs, however, fails locally but seems to do just fine on Read the Docs. It fails locally because the dependency cannot be imported. I tried adding my dependency to docs/requirements.txt as well but that didn't solve the issue. Any ideas?

Scrutinizer usage

You include a Scrutinizer code quality badge in the readme. Is there any reason why Scrutinizer is not used for more than code quality? Coverage, CI, etc. Is everything else on Scrutinizer only for paying customers? (I don't see them advertising anything as free at all, yet still code quality is obviously free, so I have no idea what is and what isn't free.)

Versioning packages

Bumpversion is not maintained anymore. There's a fork called https://github.com/c4urself/bump2version

People seem to like versioneer. https://github.com/warner/python-versioneer Perhaps that could be added?

Where to put project dependencies?

I am unsure where to put project dependencies (e.g. numpy). Options:

docs/requirements.txt
tox.ini (under [testenv])
setup.py (install_requires)
other places?

Simplify AppVeyor build matrix

AppVeyor lets you combine configuration, platform and matrix and builds each combination of the three variables on the yml config

We used this to greatly simplify our AppVeyor config. Our current version is a bit leaner too.

For example, the setup below build on 2.7-3.6 on both x86 and x64. All other related environment variables are computed and set during init.

platform:
  - x86
  - x64

environment:
  matrix:
    - PYTHON_VERSION: 2.7
    - PYTHON_VERSION: 3.3
    - PYTHON_VERSION: 3.4
    - PYTHON_VERSION: 3.5
    - PYTHON_VERSION: 3.6

init:
  # Update Environment Variables based on matrix/platform
  - set PY_VER=%PYTHON_VERSION:.=%
  - set PYTHON=C:\PYTHON%PY_VER%
  - if %PLATFORM%==x64 (set PYTHON=%PYTHON%-x64)

  # Put desired Python version first in PATH
  - set PATH=%PYTHON%;%PYTHON%\Scripts;%PATH%

install:
  - pip install --upgrade -r requirements.txt --quiet

There are many ways to integrate this into your cookiecutter template, so I opened a ticket to see if its something worth integrating to it.

LICENSE for ionelmc/cookiecutter-pylibrary

Feature request: please add a LICENSE for your repo.

This will make it easier for me to use your template at work. If you don't have a preference ISC/BSD style licenses are preferred.

Thank you for sharing your work. It is helping me improve my python skills.

Problems with Dashes in Project Names (More Sanity Checks?)

First: great project! Awesome work! 👍

I've stumbled upon some issues when entering a distribution name with dashes.

I did the following steps:

Used versions:

$ python3 --version                                                              
Python 3.4.1
$ uname -a
Linux erde 3.16.7-21-desktop #1 SMP PREEMPT Tue Apr 14 07:11:37 UTC 2015 (93c1539) x86_64 x86_64 x86_64 GNU/Linux
$ lsb-release -a
LSB Version:    n/a
Distributor ID: openSUSE project
Description:    openSUSE 13.2 (Harlequin) (x86_64)
Release:        13.2
Codename:       Harlequin

Create a virtual environment (with Python3):

$ mkdir ~/develop; cd ~/develop
$ pyvenv env3
$ pip install --upgrade pip setuptools

Install Tox and Cookiecutter:

$ pip install tox cookiecutter

Install the cookiecutter-pylibrary:

$ cookiecutter gh:ionelmc/cookiecutter-pylibrary

Answered the questions. I used mainly the default values; here is my .cookiecutterrc file:

default_context:

c_extension_optional:      'no'
c_extension_support:       'no'
codecov:                   'yes'
command_line_interface:    'plain'
coveralls:                 'no'
distribution_name:         'foo-bar'
email:                     '[email protected]'
full_name:                 'Tux Penguin'
github_username:           'tux'
landscape:                 'no'
package_name:              'foo-bar'
project_name:              'foo-bar'
project_short_description: 'An example of foo-bar'
release_date:              '2015-07-26'
repo_name:                 'foo-bar'
scrutinizer:               'no'
sphinx_theme:              'readthedocs'
test_matrix_configurator:  'no'
test_runner:               'pytest'
version:                   '0.1.0'
website:                   'http://www.example.org'
year:                      '2015'

So far, so good. However, when trying to build everything this leads to the following error message:

(env3) tux@erde:~/develop/foo-bar> tox -v
using tox.ini: /home/tux/develop/foo-bar/tox.ini
using tox-2.1.1 from /home/tux/develop/env3/lib64/python3.4/site-packages/tox/__init__.py
GLOB sdist-make: /home/tux/develop/foo-bar/setup.py
  /home/tux/develop/foo-bar$ /home/tux/develop/env3/bin/python3.4 /home/tux/develop/foo-bar/setup.py sdist --formats=zip --dist-dir /home/tux/develop/foo-bar/.tox/dist >/home/tux/develop/foo-bar/.tox/log/tox-0.log
ERROR: invocation failed (exit code 1), logfile: /home/tux/develop/foo-bar/.tox/log/tox-0.log
ERROR: actionid: tox
msg: packaging
cmdargs: ['/home/tux/develop/env3/bin/python3.4', local('/home/tux/develop/foo-bar/setup.py'), 'sdist', '--formats=zip', '--dist-dir', local('/home/tux/develop/foo-bar/.tox/dist')]
env: None

error in foo-bar setup command: ("EntryPoint must be in 'name=module:attrs [extras]' format", 'foo-bar = foo-bar.__main__:main')

ERROR: FAIL could not package project - v = InvocationError('/home/tux/develop/env3/bin/python3.4 /home/tux/develop/foo-bar/setup.py sdist --formats=zip --dist-dir /home/tux/develop/foo-bar/.tox/dist (see /home/tux/develop/foo-bar/.tox/log/tox-0.log)', 1)
(env3) tux@erde:~/develop/foo-bar>

Obviously, the dash (-) in the name seems to be the culprit. I repeated the same without any dash and it worked.

Could you add some more sanity checks to avoid such problems? It would even help to inform the user that he or she should only enter valid names at some point.