This is a template repository for python module projects.
- Python module/package
- Project Structure
- Boilerplate/Template
- Best Practices
- Configuration
- Test
- Build
- Documentation
- Scripts
- Examples
- CI/CD
-
You can use this template repository as reference to create a new repository with the same structure or clone the repository to start a new project. It will help you to organize your project structure and files. It works out of the box for most of the python projects.
-
You can customize (remove, modify or add) the files and directories as needed to meet your project requirements.
-
If you want to use the template repository directly, just click the Use this template button and follow the instructions.
-
You can use cookiecutter to generate a new project from cookiecutter branch:
# Clone the cookiecutter branch: git clone -b cookiecutter https://github.com/bybatkhuu/module.python-template.git # Install cookiecutter: pip install cookiecutter # Generate a new project from the cookiecutter template: cookiecutter -f .
- Install Python (>= v3.9) and pip (>= 23):
- [RECOMMENDED] Miniconda (v3)
- [arm64/aarch64] Miniforge (v3)
- [Python virutal environment] venv
[OPTIONAL] For DEVELOPMENT environment:
- Install git
- Setup an SSH key (video tutorial)
Tip
Skip this step, if you're going to install the package directly from PyPi or GitHub repository.
2.1. Prepare projects directory (if not exists):
# Create projects directory:
mkdir -pv ~/workspaces/projects
# Enter into projects directory:
cd ~/workspaces/projects2.2. Follow one of the below options [A], [B] or [C]:
OPTION A. Clone the repository:
git clone https://github.com/bybatkhuu/module.python-template.git && \
cd module.python-templateOPTION B. Clone the repository (for DEVELOPMENT: git + ssh key):
git clone [email protected]:bybatkhuu/module.python-template.git && \
cd module.python-templateOPTION C. Download source code:
- Download archived zip file from releases.
- Extract it into the projects directory.
Note
Choose one of the following methods to install the package [A ~ F]:
OPTION A. [RECOMMENDED] Install from PyPi:
# Install from staging TestPyPi:
pip install -i https://test.pypi.org/simple -U my-module01
# Or install from production PyPi:
# pip install -U my-module01OPTION B. Install latest version directly from GitHub repository:
pip install git+https://github.com/bybatkhuu/module.python-template.gitOPTION C. Install from the downloaded source code:
# Install directly from the source code:
pip install .
# Or install with editable mode:
pip install -e .OPTION D. Install for DEVELOPMENT environment:
pip install -r ./requirements/requirements.dev.txtOPTION E. Install from pre-built release files:
- Download
.whlor.tar.gzfile from releases - Install with pip:
# Install from .whl file:
pip install ./my_module01-[VERSION]-py3-none-any.whl
# Or install from .tar.gz file:
pip install ./my_module01-[VERSION].tar.gzOPTION F. Copy the module into the project directory (for testing):
# Install python dependencies:
pip install -r ./requirements.txt
# Copy the module source code into the project:
cp -r ./src/my_module01 [PROJECT_DIR]
# For example:
cp -r ./src/my_module01 /some/path/project/## Standard libraries
import sys
import logging
## Internal modules
from my_module01 import MyClass
logger = logging.getLogger(__name__)
if __name__ == "__main__":
logging.basicConfig(
stream=sys.stdout,
level=logging.INFO,
datefmt="%Y-%m-%d %H:%M:%S %z",
format="[%(asctime)s | %(levelname)s | %(filename)s:%(lineno)d]: %(message)s",
)
# Pre-defined variables (for customizing and testing)
_items = [0.1, 0.2, 0.3, 0.5, 0.6, 0.7, 0.8, 0.9, 1.0]
_config = {
"min_length": 4,
"max_length": 10,
"min_value": 0.0,
"max_value": 1.0,
"threshold": 0.7,
}
# Main example code
logger.info(f"Items before cleaning: {_items}")
_my_object = MyClass(items=_items, config=_config)
_items = _my_object()
logger.info(f"Items after cleaning: {_items}")
logger.info("Done!\n")👍
my_module01:
min_length: 2
max_length: 100
min_value: 0.0
max_value: 1.0
threshold: 0.5# ENV=development
# DEBUG=trueTo run tests, run the following command:
# Install python test dependencies:
pip install -r ./requirements/requirements.test.txt
# Run tests:
python -m pytest -sv -o log_cli=true
# Or use the test script:
./scripts/test.sh -l -v -cTo build the python package, run the following command:
# Install python build dependencies:
pip install -r ./requirements/requirements.build.txt
# Build python package:
python -m build
# Or use the build script:
./scripts/build.shTo build the documentation, run the following command:
# Install python documentation dependencies:
pip install -r ./requirements/requirements.docs.txt
# Serve documentation locally (for development):
mkdocs serve
# Or use the docs script:
./scripts/docs.sh
# Or build documentation:
mkdocs build
# Or use the docs script:
./scripts/docs.sh -b