# UCL ARC `python-tooling` workshop

Thank you for registering to attend the UCL Centre for Advanced Research Computing `python-tooling` workshop at the UCL _Festival of Digital Research and Scholarship_ :tada:.

## :gear: Pre-workshop setup

During the workshop you will have the opportunity to try out using the cookiecutter [`UCL-ARC/python-tooling` template](https://github.com/UCL-ARC/python-tooling) to create a Python package setup with our tooling recommendations. To use the template you will need to bring along a laptop with at least the following software tools installed,

- [cookiecutter](https://cookiecutter.readthedocs.io/en/stable/),
- [Git](https://git-scm.com/),

and ideally also,

- [the GitHub command line interface (CLI)](https://cli.github.com/),
- [pre-commit](https://pre-commit.com/),
- [tox](https://tox.wiki).

These additional three tools are required to complete some of the follow on exercises we have prepared for using the package generated with the template, so while they are not strictly needed, you will get more out of the workshop if you have them installed. For the follow on exercises you will also need an [account set up on GitHub](https://github.com/join) if you don't already have one.

An easy way to get all the software you need installed is using the tool [Conda](https://conda.io/projects/conda/en/latest/user-guide/getting-started.html) to create a dedicated environment with the necessary packages installed by following the step by step instructions below:

1. Download and install [Miniconda](https://docs.anaconda.com/free/miniconda/) following the operating system specific instructions at either
- https://docs.anaconda.com/free/miniconda/miniconda-install/ for a graphical installer
- or https://docs.anaconda.com/free/miniconda/#quick-command-line-install for installation via the command line.

If you already have Miniconda (or Anaconda) installed you can skip this step.
2. Once Miniconda is installed, you need to open a terminal window:
- On Windows: open the Start menu from the taskbar, type `miniconda` in the search field, then click `Anaconda Prompt (miniconda3)` from the results (or `Anaconda Prompt (anaconda3)` if using a previous Anaconda installation).
- On MacOS: click the Launchpad icon in the Dock, type `Terminal` in the search field, then click `Terminal` from the results.
- On Linux: open the default terminal application installed in your distribution.
3. Once you have a terminal window open you should see text `(base)` as part of your [command prompt](https://en.wikipedia.org/wiki/Command-line_interface#Command_prompt) if Minconda has been installed and set up correctly, indicating you currently have the default `base` environment active. If this is the case you should run

   conda create -y -n python-tooling -c conda-forge cookiecutter git gh pre-commit tox

to create a new environment named `python-tooling` in to which will be installed the packages necessary for creating and using a package using the `UCL-ARC/python-tooling` cookiecutter template.
4. To check that all the dependencies have installed correctly in the new environment first activate the environment by running

   conda activate python-tooling

at which point you should see `(base)` in the command prompt change to `(python-tooling)`, Then try running each of the following commands in turn, one at a time,

   cookiecutter --version
   gh --version
   git --version
   pre-commit --version
   tox --version

For each command you should see some text outputted to the terminal giving details of the installed versions of the applications - the output itself is not important as long as you do not see any error messages.
6. If you also want to try out creating a GitHub repository for the package you will need to [sign-up for a free GitHub account](https://github.com/join) if you don't already have one. Once you have a GitHub account, open a terminal window - you can either use the same one as previously if you still have it open, or open a new terminal window as described in step 2 and then activate the `python-tooling` Conda environment by running

   conda activate python-tooling

Once you have a terminal window with the `python-tooling` environment active (you should see `(python-tooling)` in your command prompt) run

   gh auth login

to authenticate the GitHub command line interface tool `gh` with your GitHub account credentials. The tool will ask you a series of question, for most of which you can select the default options by just hitting the `Enter` key. Specifically select:
- `GitHub.com` for account to log into,
- `HTTPS` for preferred protocol,
- `Y` to authenticate Git with your GitHub credentials,
- `Login with a web browser` as the method to authenticate.

Once you have selected all these options, a one-time code will be printed to the terminal. You need to copy this code and then hit the `Enter` key to open a page to complete the authentication in your default browser. Once you have entered and submitted the code in the authenticatication page, you should see a `Authentication complete` message appear in the terminal window.