robinandeer / cookiecutter-pyvanguard

Bleeding edge Cookiecutter template for Python development

Hi there 👋

I work as a Staff Engineer at Hedvig where we're building a new kind of insurance company.

My team is responsible for the online purchase journey 🛍️. We use GraphQL, React, TypeScript, and Next.js to build a modern, scalable and e-commerse inspired shopping experience.

Personally, I'm interested in all things Web Development - from the frontend to the backend. I find it the most exciting app platform to work with today.

You can find my blog at robinandeer.com where I write about my experiences with Web Development and other things I find interesting.

Latest blog post

Progressive enhancement as productivity booster

Progressive enhancement boosts productivity when building web apps. It keep me focused and helps me break down complex features.

cookiecutter-pyvanguard's Issues

Vagrant / ansible use notes?

Hi @robinandeer, thanks for the nice cookiecutter template!

From the repo README:

Vagrant to define and share development environments, provisioned by Ansible.

this is a wonderful concept, and ideally would be included as part of any collaborative Python-based project. This alone was ultimately the reason I started to test out this template. After installing, I've been greping around, trying to find where this exists, but I don't find any references to Vagrant or ansible.

Any pointers? Thanks again, much appreciated.

Populate install_requires from requirements.txt

Yipee! This is a nice recipe:

from pip.req import parse_requirements

# parse_requirements() returns generator of pip.req.InstallRequirement objects
install_reqs = parse_requirements(<requirements_path>)

# reqs is a list of requirement
# e.g. ['django==1.5.1', 'mezzanine==1.4.6']
reqs = [str(ir.req) for ir in install_reqs]

setup(
...
    install_requires=reqs
)

Reference: http://stackoverflow.com/questions/14399534/how-can-i-reference-requirements-txt-for-the-install-requires-kwarg-in-setuptool

Inspiration

https://github.com/kirang89/bootstrapy

Automate pip requirements files

https://github.com/bndr/pipreqs

• investigate if this can be used to populate setup.py as well

Cannot clone repo on Windows

I was attempting to work with this cookiecutter on a Windows machine, but cloning the repo fails because of the templated directories and filenames containing the | character. That is an invalid character for directories and filenames on Windows.

I checked the commit history to try to figure out why those are being templated, but it wasn't really clear to me. Is there perhaps an alternate way to fix whatever the problem was?

C:\Users\Loren\.cookiecutters> git clone https://github.com/robinandeer/cookiecutter-pyvanguard.git
Cloning into 'cookiecutter-pyvanguard'...
remote: Counting objects: 648, done.
remote: Total 648 (delta 0), reused 0 (delta 0), pack-reused 648
Receiving objects: 100% (648/648), 193.15 KiB | 0 bytes/s, done.
Resolving deltas: 100% (339/339), done.
Checking connectivity... done.
error: unable to create file {{cookiecutter.repo_name}}/tests/test_{{ cookiecutter.repo_name|replace("-", "_") }}.py (Invalid argument)
fatal: cannot create directory at '{{cookiecutter.repo_name}}/{{cookiecutter.repo_name|replace("-", "_")}}': Invalid argument
warning: Clone succeeded, but checkout failed.
You can inspect what was checked out with 'git status'
and retry the checkout with 'git checkout -f HEAD'

Add when-changed support

A new utility to run commands when files changes. Could be added to the tasks.py file.

https://github.com/joh/when-changed

More badges

https://pypip.in/

.. image:: https://pypip.in/d/{{ cookiecutter.repo_name }}/badge.png
        :target: https://pypi.python.org/pypi/{{ cookiecutter.repo_name }}

Use environment.yml file

Instead of splitting up conda and pip requirements

Jekyll vs. Sphinx

Jekyll vs. Sphinx

• Jekyll was primarily intended as a blogging tool, Sphinx is a documentation-first tool.
  • Helpful templates for Jekyll exists https://github.com/bruth/jekyll-docs-template/
• Jekyll is a versatile tools that you can use for many things, Sphinx is something I would only use for Python documentation.
• Jekyll is written in Ruby (another dependency) whereas Sphinx is a highly standardised Python native tool.
• I've always enjoyed developing themes etc. more for Jekyll (built in auto-updating server) over Sphinx. With the new Jekyll 2.0 you can even compile SCSS files which hopefully is brought to GitHub soon.

Markup: Markdown vs. ReStructuredText

I think Markdown is hands down simpler to read/write. I will keep writing my READMEs etc. in Markdown which makes Sphinx less appealing.

+1 Jekyll

Hosting: GitHub Pages vs. ReadTheDocs

• Both tools can automatically update the docs after a new commit push
• GitHub pages separates your docs to a specific branch but keeps everything together in the repo
• It's more straight forward to setup custom domains with ReadTheDocs

Features

• Sphinx has the autodoc plugin which let's you pull in inline documentation and generate API docs (DRY)
  • I don't know if I find API docs super necessary, though. I think I'm just as likely to dig into the source code at GitHub straight away rather than reading a rendered version of it. My first instinct is to launch iPython and inspect the function docstring.
• Jekyll benefits from the tight GitHub integration, e.g. https://help.github.com/articles/mentions-on-github-pages

Usability

• Sphinx has always been a bit of a mystery to me (e.g. how you have to predefine internal links)
• Jekyll supports (a subset?) of the excellent Liquid template language (similar to Jinja2)

Python packages can't have dash in the name

Try to include Jinja replace pipe in the directory name of the Python package root.

Entry points should be versioned!

Like PyTest:

entry_points={'pytest11': ['pytest_cov = pytest_cov']}

Otherwise old installed plugins might interfere with newer releases.

invoke tasks is *nix specific

The tasks.py file is using *nix specific commands (rm, find etc), which are not natively supported on MS Windows.

It shall be rather easy to rewrite the code to be platform independent,
personally, I prefer using py library, which allows to do so very well.

from py.path import local


def clean():
    """clean - remove build artifacts."""
    for dirname in ['build',
                    'dist',
                    'vanguard.egg-info',
                    "{{ cookiecutter.repo_name|replace('-', '_') }}.egg-info"]:
        dirpath = local(dirname)
        if dirpath.exists():
            dirpath.remove(rec=1)
    for mask in ["__pycache__", "*.pyc", "*.pyo", "*~"]:
        map(local.remove, local().visit(mask))

    log.info('cleaned up')

PyTest plugins

Integrate with coverage in one command:
https://github.com/schlamar/pytest-cov

$ py.test --cov-report html --cov chanjo tests/