Installation

Following Sections provide overview on how to install the package.

Using This Project Template

Use the following guide to fully take advantage of this project template:

1. Install Pyenv (only if not already present):

   1. Download and install using bash:

      $ curl https://pyenv.run | bash
      

   2. Add the following lines to your ~/.bashrc to make pyenv known to your system:

      $ export PATH="~/.pyenv/bin:$PATH"
      $ eval "$(pyenv init -)"
      $ eval "$(pyenv virtualenv-init -)"
      

   3. Open a new shell, or source ~/.bashrc in your current shell

   4. Install the Python build dependencies for your platform, using one of the commands listed in the official instructions. For example, on a recent Ubuntu this would be:

      $ sudo apt update && sudo apt install -y make build-essential libssl-dev zlib1g-dev \
      $ libbz2-dev libreadline-dev libsqlite3-dev wget curl llvm libncurses5-dev \
      $ libncursesw5-dev xz-utils tk-dev libffi-dev liblzma-dev python-openssl git
      

2. Create a new folder representing your repo/published package using kebab case:

   $ mkdir my-project
   

3. Install the desired python versions using pyenv:

   $ pyenv install 3.10.4
   $ pyenv install 3.9.13
   $ pyenv install 3.8.13
   

4. Clone the hpmpy-template into your new local repo folder:

   $ git clone https://github.com/tZ3ma/hpmpy-project my-project
   

5. Change into the new project folder and ctivate the desired python versions

   $ cd my-project
   $ pyenv local 3.10.4 3.9.13 3.8.13
   

6. Install poetry (only if not already present)

   1. Download the poetry install script and run it

      $ curl -sSL https://raw.githubusercontent.com/python-poetry/poetry/master/get-poetry.py | python
      

   2. Open a new shell or source ~/.poetry/env in your current shell

7. Install nox:

   $ pip install --user --upgrade nox
   

8. Rename all hpmpy instances after your project using git grep by replacing MY-PROJECT below:

   $ git grep -lz hpmpy-project | xargs -0 sed -i -e "s/hpmpy-project/MY-PROJECT/g"
   $ git grep -lz hpmpy_project | xargs -0 sed -i -e "s/hpmpy_project/MY_PROJECT/g"
   

9. Rename the src/hpmpy_project package folder by replacing MY_PROJECT below:

   $ mv src/hpmpy_project src/MY_PROJECT
   

10. Install your package using poetry:

    $ poetry install
    

11. Run your first nox sessions:

    $ nox
    

12. Bump your package version to 0.1.0:

    $ poetry version minor
    

    Modify the tests/test_version.py file accordingly

13. Create a remote repo on Github

14. Integrate your PyPI and TestPyPI API-Token as explained in the release workflow sections.

15. Add coverage reports using Codecov:

    1. Go to the Codecov website and login using your Github account.

    2. Click on not yet setup and copy the API-Token in point 2.

    3. Make it a Secret in your remote repo called CODECOV_TOKEN

    4. Your next push to the remote repo will trigger the test workflow in .github/workflows/tests.yml which will then automatically upload the coverage report to Codecov

15. Install and add git pre-commit hooks:

    pip install --user --upgrade pre-commit
    pre-commit install
    

16. Add, commit and push all changes to your new remote repo:

    $ git add -A
    $ git commit -m "Project Initialization"
    $ git remote set-url origin https://github.com/GIT-USER/MY-PROJECT.git
    $ git branch -M main
    $ git push -u origin main
    

17. All set up! Now branch of your main branch to create the develop branch and add first implementations:

    1. Create switch to new develop branch:

       $ git checkout -b develop
       

    2. Modify the README.rst, docs/index.rst and the docs/source/getting_started/installation.rst files to refelct your project description.

    3. Add sub-packages and/or modules to the src/strutils/ folder

    4. Add, commit and push all changes/addition to your remote repo

       $ git add -A
       $ git commit -m "Initial Implementation"
       $ git push -u origin develop
       

18. (Optional) Create accounts on Codacy, Codeclimate and Scrutinizer for code quality checks using you Github account.

19. All done! Make sure to checkout the Workflows Developer Guide to acquaint yourself with the usage of Poetry, Nox and Github.

Development Install of Your Package Created with this Template

1. Install Pyenv (only if not already present)

2. Install Poetry and Nox (only if not already present)

3. Clone the repo to a local directory (uses package name if square bracket part is omitted):

   $ git clone https://github.com/tZ3ma/hpmpy-project [hpmpy-project-develop]
   

4. Change to the new local repo folder and activate the desired python versions using pyenv:

   $ cd strutils
   
   $ pyenv install 3.10.4 (adjust version to your needs)
   $ pyenv install 3.9.13 (optional)
   $ pyenv install 3.8.13 (optional)
   
   $ pyenv local 3.10.4 3.9.13 3.8.13 (activate those desired)
   

5. Install the package with development requirements:

   $ poetry install
   

56 Auto generate and activate a virtual environment where the installed package

is installed:

$ poetry shell

7. (Optional) Alternatively, you can now run an interactive Python session, or the command-line interface if your package supports it:

   $ poetry run python
   $ poetry run hpmpy-project
   

User Install of Your Package Created with this Template

Use the following advice to install the standard / user version of this package, once you have at least one push on your main and develop branch (so the respective release workflows are triggered).

Linux

Install using a console with your virtual environment activated:

Latest Stable Version

$ pip install hpmpy-project

Latest Development Version (potentially unstable)

$ pip install --index-url https://test.pypi.org/simple/ --extra-index-url https://pypi.org/simple/ hpmpy-project

This installs the TestPyPI version of MY-PROJECT while resolving the dependencies on PyPI.