- clone this repository to your desktop
- open it in your favorite python code editor (e.g. atom or spyder)
- for atom, we recommend installing the package plugins (from the command line):
apm install atom-ide-terminal
: let's you start a terminal from menuPackages
->Atom IDE Terminal
->Toggle
apm install ide-python
: provides python programming tools including color-coding for.py
filesapm install autocomplete-python
: provides autocompletion for python code- then launch atom in the current directory from the command line with
atom .
- start a terminal and make sure you are in the repo folder (i.e. the folder where the
setup.py
is located) - install the library from the terminal:
conda activate class ## install the library in development mode pip install -e .
- now in any python session within this environment (start with e.g.
python3.7
from terminal) you can import your library functions, e.g.:from awesome import module module.hello()
- or call functions listed in the
setup.py
->entry_points
directly from the command-line:hello
- any code changes you make will be automatically reflected in the command-line calls and after each new import of the library in a python session - but don't use the console for testing!
- rather than testing your library interactively, you should write tests that automatically check your functionality
- install
pytest
withconda install -c anaconda pytest
- to run a specific test file, you can call e.g.
pytest tests/test_library.py
from the terminal - take a look at thetests/test_library.py
file to see what it checks - to run doctests on a code file you can call e.g.
pytest src/awesome/module.py --doctest-modules
- to run all tests and doctests for your entire library simply run
pytest --doctest-modules
(i.e. without specifying a specific folder or file) - to run all your tests and doctests automatically in multiple virtual environments to ensure your library works outside your current workspace and in multiple python versions (e.g. python 2.7 and python 3.7), install
conda install -c conda-forge tox
and calltox
from the terminal - to run all tests for just one specific version, use e.g.
tox -e py37
- take a look at thetox.ini
to see how it is setup and usetox -l
to find the list of available testing environments
- to get started with automatically generating documentation using sphinx, install it with
conda install -c anaconda sphinx sphinx_rtd_theme
and for markdown supportconda install -c conda-forge recommonmark
- run
sphinx-build sphinx docs
form the command line - check the
docs
folder and open theindex.html
to see your documentation - to run this routinely and also check that your documentation has valid links to other pages, simply run
tox -e docs
(seetox.ini
for what it does) - to enable access to this documentation online, make sure to commit the contents of the
docs
folder to GitHub and go to your repository Settings --> GitHub Pages --> Source: selectmaster branch/docs folder
- alternatively (or additionally) you can log into read the docs with your GitHub account and import your documentation directly from your repository to have it hosted on read the docs
- start your modifications by changing the version in
src/awesome/version.py
and see how it affects callinghello
andtox
- give your library a unique name by changing awesome to something else everywhere it occurs in
setup.py
, the name of thesrc/awesome
folder, as well as insphinx/conf.py
andspinx/reference.rst
(the latter two to also have your documentation reflect the changes) - implement new modules and functions, document them with docstring, and add tests for them - keep testing your library along the way to see how it is doing!
- make sure to keep
setup.py
up-to-date with the dependencies and other information (for additional information, here is the documentation forsetuptools
) (Note that there is a gradual movement in the python community away fromsetup.py
and towards apyrproject.toml
file with different project dependency managers such as e.g. poetry - the final best practice solution is still in flux so we are recommending to stick withsetup.py
for now) - make sure to work with git to keep track of your changes and push commits back to GitHub
- continuous integration (i.e. automatic testing) with every commit is very useful and this repo contains a basic
.travis.yml
file to make this possible
- there are various types of linters available for python, we recommend black which is quite opinionated but gets the job done easily and efficiently
- to install, run
conda install -c anaconda black
- to use, run e.g.
black src
orblack tests
, it will reformat all python files in the respective folders to fit its prescribed coding style.
- to figure out how much of your code base is actually covered with tests, the
coverage
library is a great tool - to install, run
conda install -c anaconda coverage
- to use, run
coverage run -m pytest --doctest-modules
and thencoverage report
for a summary of the results - for a more detailed view, run
coverage report
and launch the createdhtmlcov/index.html
file
-
your users (or you) can install your library directly from GitHub using the following syntax:
pip install git+https://github.com/USER/REPO.git
-
for wider distribution it is useful to upload your library to the Python Package Index (PyPI) at which point it will become available to your users via regular
pip
install:pip install LIBNAME
-
if you have already settled on a name for your library (it must be unique on PyPI!), it is worthwhile registering the name with PyPI using the following command from your main library directory (you'll need a PyPI account first and then user your login credentials):
python setup.py register
-
and to actually upload/update your library on PyPI:
python setup.py sdist upload
-
note that the
sdist
part creates a distribution.tar.gz
file in yourdist
folder which you could also manually distribute to others (or use to test-install your library although we recommend taking the GitHub route for this)