A minimal memo for start coding in python: description of main components, package structure, boilerplate

python-get-started-guide.md

Python Get Started Guide

This is a minimal introduction to a python package setup, describing some technologies and available method to achieve the get started goal.

PyPA is the Python Package Authority.

PyPUG is the Python Package User Guide.

A python module is the code saved in a file.

There are different type of packages:

• (Import) Package, i.e., a namespace.
• (Distrubition) Package which is a shareable/installable package (source vs build).

The distribution can be:

• source distrubtion: sdist
• build distribution:
  • bdist_egg (deprecated),
  • bdist_whell

Wheel (distribution format) can be:

• Unversal = file installable and usable by python: no compilation, python read code.
• Pure Python = python 2.x or 3.x specific, even this is only code.
• Platform = Linux, Windows.

PyPI is the Python Packages Index: anyone can upload a package to it. Note that this is not pypy (JIT - Just In Time (compilation) - implementation for python)

Package Components

root
|-- data
|   |--	data_file
|-- DESCRIPTION.rts
|-- MANIFEST.in
|-- README.rts
|-- sample
|   |--	__init__.py
|   |--	package_data.dat
|-- setup.cfg
|-- setup.py
|-- tests
    |--	__init__.py 
    |-- simple_test.py

Code

setup.py

Contains information about package. It is an executable to complete package tast (build, upload...).

from setuptools import setup, find_packages

setup(
	name='',
	version='' # PEP440
	descrition=
	long_description
	url
	author
	author_email
	license='MIT'
	classifier=[
		'Devlop Status :: 3 - Alpha',
		'Indented Audience :: Developers',
		'License :: OSI Approved :: MIT License',
		'Programming Language :: Python :: 3.7'
	],
	keywords
	packages=find_packages(exclude=['docs','tests*']  # used to install all containded in the package directory, excluding only some files.
	install_requires=['requests'],  # list dependencies, can even specify version... 
	package_data={  # ship extra data with package (not python code but needed), package use this data.
		'sample': ['package_data.dat']
	}
	data_files=None
	# scripts = ,  # should be ignored.
	entry_point={
		'console_scripts': [  # defines script available in path.
			'hello=blabla:say_hello',  # create a wrapper executable for say_hello.
		]
	}
)

It is platform indipendet.

setup.cfg

Configuration for wheel.

MANIFEST.in

Has a listing of anything in package that is needed by it.

README.rst

Used as index page. Can be used in setup.py.

DESCRIPTION.rts

Description for PyPI listing.

LICENSE

Not a secret.

Tests

./tests

Uses tox (tox.ini) as test runner. It runs tests in multiple env.

Docs

./docs

CI

.travis.yml Travis is the most famous service for continuos integration. It can be integrate in GitHub. It allows to specify in what env run tests.

requirements.txt

List all the requirements needed from the package. Can be useful to install all the package requirements.

.gitignore

Not a secret.

Other files

• HISTORY.rst
• CHANGES.rst or CHANGELOG.rst
• CONTRIBUTING.rst
• AUTHORS.rst

Setup

Requirements

pip install whell
pip install twine
pip install tox

Boilerplate? CookieCutter

pip install cookiecutter

Allows to download preconfigured repo, setup and modify it.

Virtualenv

From virtualenvwrapper

mkvirtualenv abc

Run cookoue cutter

cookiecutter git_url
...
configuration questions from cookiecutter...

Git init

Setup your git repo.

Add code

...

def say_hello(): ...
def hello(): ...

Add tests

Code the unit tests.

Run test

Tests can be run with tox.

tox.ini is automatically created by cookiecutter, tox read the ini files and execute the tests. Note: tox creates venv on the fly and run tests in it.

Services

• git: github, bitbucket...
• Continuos integration:

add repo to travis-ci.org
click sync button

• git push
  • triggers travis-ci
  • tox run tests (e.g. 2.7, 3.3, pypy)
• read the docs
  • link repo to read the docs
  • generate documentation (scheleton generated by cookiecutter)
• PyPI
  • create account (can be done py setup.py but it does not use ssl)
  • save PyPI setting in $HOME/.pypirc
  • the file is:

[distutils]
index-server=pypi

[pypi]
repository = pypy.python.org/pypi
username = ...
password = ...

Build

With PyPI

./setup.py sdist
./setup.py bdest_wheel

Sign distribution

gpg --detach-sign -a

Register pacage

Upload

twine upload dist/*

Develop mode

Allows to distribute package and on PyPI but relate the local distribution version to the local source version. In order to do this python creates a symlink to source file in install directory.

You can use package immediatly after updates.

./setup.py develop
or
pip install -e

Python versioneer

GitHub project. Dynamically manage version based on git tag. If you do not specify tag in git, it automatically takes the git hash and handle it in package version.

Other tips

Closed source?

• jankings ??? continuos integration
• githash ??? intesad of github
• dev py -> run pyPI internally -> local cache, repo of our stuff

RPM for python tingh

There are some tools: they are not automated, but exists, so...