mapbox / pyskel

Skeleton of a Python package

pyskel

A skeleton of a Python package with CLI and test suite included.

Customization quick start

To use pyskel as the start of a new project, do the following, preferably in a virtual environment. Clone the repo.

git clone https://github.com/mapbox/pyskel myproject
cd myproject

Replace all occurrences of 'pyskel' with the name of your own project. (Note: the commands below require bash, find, and sed and are yet tested only on OS X.)

if [ -d pyskel ]; then find . -not -path './.git*' -type f -exec sed -i '' -e 's/pyskel/myproject/g' {} + ; fi
mv pyskel myproject

Then install in locally editable (-e) mode and run the tests.

pip install -e .[test]
py.test

Finally, give the command line program a try.

myproject --help
myproject 4

To help prevent uncustomized forks of pyskel from being uploaded to PyPI, I've configured the setup's upload command to dry run. Make sure to remove this configuration from setup.cfg when you customize pyskel.

Please also note that the Travis-CI and Coveralls badge URLs and links in the README contain the string 'mapbox.' You'll need to change this to your own user or organization name and turn on the webhooks for your new project.

A post on the Mapbox blog has more information about this project: https://www.mapbox.com/blog/pyskel/.

See also

Here are a few other tools for initializing Python projects.

• Paste Script's paster create is one that I've used for a long time.
• cookiecutter-pypackage is a Cookiecutter template for a Python package. Cookiecutter supports many languages, includes Travis configuration and much more.

pyskel's Issues

Reuse metadata from module in setup.py

It is common to put __version__, __author__ and other metadata in your module, so users of your module could inspect it:

>>> import docopt
>>> docopt.__version__
'0.6.1'

But that creates duplication, since you need to specify this information in setup.py file as well.

For projects without dependencies, you can just import your local module, and set the keyword arguments of setup function call to the module attributes, like here:

https://github.com/keleshev/schema/blob/b81c544263a59d5bb3caa37d7628cb00e7d08288/setup.py#L8

For modules with dependencies it is a bit more complicated, but I have seen people creating a version.py file to store just the version, and import it in setup.py. I also have seen projects parse their modules to extract version without evaluating the Python file. However, a nice way would probably to use a special file for metadata, like, maybe __meta__.py which only contains metadata:

__version__ = '0.6.1'
__author__ = 'Vladimir Keleshev'
...

And then make setup.py import it and use it.

I have no example of that, since all my open-source projects have no dependencies, that means I can import metadata from them during installation.

License of pyskel

I'm wondering if it would be possible to re-license pyskel as basically public domain; basically I believe the point and most useful use is if anyone can take this and start working with this as base. There's not many contributors yet, otherwise I would not even suggest this.

The reason why I suggest this is that just for using a skeleton that will mostly be replaced anyway during development, may not justify the copyright notice requirement.

I have my doubts if setup.py or setup.cfg truly are even copyrightable, but this would have to be explicitly stated. It's not a problem if there's a placeholder license in place, although choosing the license should probably be an explicit choice for new projects in most cases.

To be explicit, I give my permission to re-license my earlier contribution to public domain.

Cookiecutter

It would be cool if this was a https://github.com/audreyr/cookiecutter template :)

Use semantic versioning

Semantic versioning (semver.org) is a versioning scheme which specifies format and meaning of versions. It so happens it is a valid subset of PEP 440 versioning scheme, but it is more strict and more widely adopted.

Why no cookiecutter

It looks like yet another highly specialized scaffolding desision. And grep/sed magic doesn't looks very fun. Why not use something like more flexible and generic, like popular cookiecutter templates https://github.com/audreyr/cookiecutter-pypackage? It seems to me that everything in pyskel can be easily implemented in cookiecutter template.

Use reStructuredText for README

If you use reStructuredText for README then PyPI will render it nicely, instead of as plain text.

Example 1: https://pypi.python.org/pypi/docopt

I have seen people using Markdown just because it highlights your Python code on GitHub, but reStructuredText can be highlighted as well, you just need to declare you code blocks as Python:

.. code:: python
    from docopt import docopt

Example 2: https://github.com/docopt/docopt/blob/1937a1c9041e0f580d2890d38bb71c0a0623847f/README.rst

Note, both examples are rendering of the same reST file, one on PyPI, another—GitHub.

Can't clone

I was interested to try out your package but can't get past the first step. When I try
git clone [email protected]:mapbox/pyskel.git myproject
I get the following error message;

Permission denied (publickey).
fatal: Could not read from remote repository.

Please make sure you have the correct access rights
and the repository exists.