copyme

A simple template for python development. Use this repository as a template for developing a python library or package.

Templates

When copying files from this repo, remember that they are templates. So:

1. look for [CHANGE THIS] for mandatory modifications;
2. look for [CHECK THIS] for possible modifications;
3. look for [EXAMPLE] for simple examples (comment or uncomment it if needed);
4. look for [ADD MORE IF NEDDED] for possible extra features;
5. placeholders are designated by curly braces: {replace-this}.

Configuration files

This repository relies on several configuration files that are essential for the proper functioning of the template. Each file has a specific role, and some of them work together, so they should be edited thoughtfully. Below is an overview of the main configuration files and what you should know about them.

Repo layout

A standard python repo may use the following layout. This layout is known as src layout, since it stores the source code under a src/{repo} folder.

See more on flat vs src layout

{repository}/
│
├── LICENSE
├── README.md                     # [CHECK THIS] this file (landing page)
├── .gitignore                    # [CHECK THIS] configuration of git vcs ignoring system
├── pyproject.toml                # [CHECK THIS] configuration of python project
├── MANIFEST.in                   # [CHECK THIS] configuration of source distribution
|
├── .github/                      # github folder
│    └── workflows/               # folder for continuous integration services
│         ├── style.py            # [CHECK THIS] configuration file for style check workflow
│         ├── tests.py            # [CHECK THIS] configuration file for tests workflow
│         └── docs.yml            # [CHECK THIS] configuration file for docs build workflow
│
├── dev/                          # development folder
│    ├── checkout.py              # checkout script
│    ├── docs.py                  # build docs script
│    ├── style.py                 # style script
│    ├── tests.py                 # testing script
│    └── templates-ci/            # templates for CI
│
├── docs/                         # documentation folder
│    ├── about.rst                # info about the repo
│    ├── api.rst                  # api reference using sphinx autodoc
│    ├── conf.py                  # [CHECK THIS] configuration file for sphinx
│    ├── dummy.md                 # markdown docs also works
│    ├── index.rst                # home page for documentation
│    ├── usage.rst                # instructions for using this repo
│    ├── make.bat                 # (optional) [generated] sphinx auxiliar file 
│    ├── Makefile                 # (optional) [generated] sphinx auxiliar file 
│    ├── figs/                    # figs-only files         
│    ├── data/                    # docs-only data
│    ├── generated/               # [generated] sphinx created files 
│    ├── _templates/              # [ignored] [generated] sphinx created stuff
│    ├── _static/                 # [generated] sphinx created stuff
│    └── _build/                  # [ignored] [generated] sphinx build
│
├── src/                          # source code folder
│    ├── {repository}.egg-info    # [ignored] [generated] files for local development
│    └── {repository}/            # [CHANGE THIS] source code root
│         ├── __init__.py         # template init file
│         ├── module.py           # template module
│         ├── ...                 # develop your modules
│         ├── mypackage/          # template package
│         │    └── submodule.py
│         └── data/               # run-time data
│
├── examples/                     # (optional) learning resources 
│    ├── examples_01.ipynb    
│    └── examples_02.ipynb            
│
└── tests/                        # testing code folder
     ├── conftest.py              # [CHECK THIS] configuration file of tests
     ├──unit/                     # unit tests package     
     │    └── test_module.py      # template module for unit tests
     ├── bcmk/                    # benchmarking tests package
     │    └── test_bcmk.py        # template module for benchmarking tests
     ├── data/                    # test-only data
     │     ├── test_data.csv
     │     ├── datasets.csv       # table of remote datasets
     │     └── dataset1/          # [ignored] subfolders in data
     └── outputs/                 # [ignored] tests outputs