# 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...