diff --git a/README.md b/README.md index 69cad73..9f7f452 100644 --- a/README.md +++ b/README.md @@ -13,15 +13,15 @@ The workshop timings are as follows: You can find the initial steps for the workshop sessions here: -Session X - Enviornments - +Session 1 - Environments and Software Installation - Part 1: Getting Started - [here](/environments/1_getting_started.md) - Part 2: Dependencies - [here](/environments/2_dependencies.md) -Session X - Git and Version Control - +Session 2 - Git and Version Control +- Part 1: Version Control - [here](/version_control/1_version_control.md) +- Part 2: Git - [here](/version_control/2_git.md) -Session X - Code Quality +Session 3 - Code Quality - Part 1: Code Quality 101 - [here](/code_quality/1_code_quality.md) - Part 2: Introduction to Pylint - [here](/code_quality/2_pylint.md) - Part 3: Introduction to Black - [here](/code_quality/3_black.md) @@ -29,5 +29,6 @@ Session X - Code Quality - Part 5: Introduction to pre-commit - [here](/code_quality/5_precommit.md) - Part 6: Final Remarks - [here](/code_quality/6_final_remarks.md) - -Session X - Pytest and Testing Code +Session 4 - Testing Code +- Part 1: Testing - [here](/code_testing/1_code_testing.md) +- Part 2: Pytest - [here](/code_testing/2_pytest.md) diff --git a/code_quality/1_code_quality.md b/code_quality/1_code_quality.md index 67ccb5c..79c3441 100644 --- a/code_quality/1_code_quality.md +++ b/code_quality/1_code_quality.md @@ -27,8 +27,11 @@ To stop this endless cycle of drama with software development, software engineer One such standard that belongs to the Python community is the PEP 8 standard (or style guide). [PEPs](https://peps.python.org/) are Python community parlance for ratified and agreed ways of doing things that all developers of tools in the language should adhere to. There are many useful PEPs but in this particular workshop, we will focus on [PEP 8](https://peps.python.org/pep-0008/). -Activity: Have a look over the two links above just to appreciate what information they contain. +*Activity*: Have a look over the two links above just to appreciate what information they contain. The reason we use standards, is that they lead to cleaner code that is more easy to share, if we all write and learn to read code in a particular format, then contributing to other projects becomes very easy. Which means our code is a lot easier to maintain as it grows, both in its size and in community. This course is designed to give you an introduction to some of the types of tools that are available to us as developers and how to get started using them. Often the difficult bit is simply getting going rather than learning about the advanced features! + +[Next](2_pylint.md) +[Home](../) diff --git a/code_quality/2_pylint.md b/code_quality/2_pylint.md index 0a29516..878c011 100644 --- a/code_quality/2_pylint.md +++ b/code_quality/2_pylint.md @@ -85,11 +85,13 @@ What do you see and what does it mean? You will notice that there are listed a bunch of bad indentation warnings and a few other warnings, and you will also it grades the code out of 10, this one is pretty shocking! If you are not sure what these mean and how to fix them, then consult the [PEP 8](https://peps.python.org/pep-0008/) standard where it will tell you specifically what the code should have looked like. -Activity: Use the PEP 8 standard and Pylint together to fix this code. Can you get this to zero warnings and a code score of 10? +*Activity*: Use the PEP 8 standard and Pylint together to fix this code. Can you get this to zero warnings and a code score of 10? -Activity: Can you find a random program on the internet or even one you have written yourself and apply Pylint to it? +*Activity*: Can you find a random program on the internet or even one you have written yourself and apply Pylint to it? That is all there is to using Pylint, you can imagine, this was a small code. Imagine you had just inherited thousands of lines or tens of thousands or even a million lines of code. You aren't going to fix it all by hand any time fast, and this effort is what we call technical debt. Technical debt is a concept in programming where we measure the effort required versus the benefit of doing it, for massive code bases it would be a big effort to standardise a badly written code base. This is where the next tool comes in! +[Next](3_black.md) +[Home](../) diff --git a/code_quality/3_black.md b/code_quality/3_black.md index f6cd09d..1536dd1 100644 --- a/code_quality/3_black.md +++ b/code_quality/3_black.md @@ -96,7 +96,9 @@ What do you see now, compared to the very first time? You are probably noticing it has fixed a whole bunch of things but a few minor things remain. Usually things that remain will be things like the docstrings etc, since Black cannot interpret what your code is supposed to do and add documentation (though this might change in the post-chatGPT era!!!). -Activity: Can you find a random program on the internet or even one you have written yourself and apply Black to it? +*Activity*: Can you find a random program on the internet or even one you have written yourself and apply Black to it? The upshot is that you would have a lot less work to do on minor issues than if you only used Pylint and manual fixing, so the technical debt of maintaining high quality code is even lower. +[Next](4_isort.md) +[Home](../) diff --git a/code_quality/4_isort.md b/code_quality/4_isort.md index 4afbdfa..2746b12 100644 --- a/code_quality/4_isort.md +++ b/code_quality/4_isort.md @@ -96,6 +96,7 @@ cat 3_random_import.py You will see it is much, much more organised and easier to read. -Activity: Can you find a random program on the internet or even one you have written yourself and apply isort to it? - +*Activity*: Can you find a random program on the internet or even one you have written yourself and apply isort to it? +[Next](5_precommit.md) +[Home](../) diff --git a/code_quality/5_precommit.md b/code_quality/5_precommit.md index 0500c7e..6cfdac6 100644 --- a/code_quality/5_precommit.md +++ b/code_quality/5_precommit.md @@ -192,3 +192,5 @@ git commit -m "adding some better code for the tutorial" So hopefully, now you can understand the power that these tools can bring to empower developers to write better code without having to spend lots of time learning standards first!! +[Next](6_final_remarks.md) +[Home](../) diff --git a/code_quality/6_final_remarks.md b/code_quality/6_final_remarks.md index c3719c0..aa7ebe7 100644 --- a/code_quality/6_final_remarks.md +++ b/code_quality/6_final_remarks.md @@ -8,3 +8,4 @@ We have not covered the use of these tools with github which is an online softwa Finally, you are encouraged to pick up and make use of these tools in your everyday projects involving code, not only do they improve your code for you, but you will also learn to write code that is compliant with these systems over time and as a result, vastly increase your skill. Perhaps as an final incentive, most modern careers at the scientific, data science and scientific software engineering will require some base skills in these technologies. +[Home](../) diff --git a/code_testing/1_code_testing.md b/code_testing/1_code_testing.md index 24adc20..24ed2be 100644 --- a/code_testing/1_code_testing.md +++ b/code_testing/1_code_testing.md @@ -1,10 +1,10 @@ -## Code Testing +# Code Testing One of the most important factors for a scientific code is being correct. We want to be able to check that the code is giving the answer we expect and that any changes to the code are not inadvertantly changing the output. This is why tests are a part of high quality code. -# Types of Tests +## Types of Tests Unit tests are small tests that each test a particullar part (or unit) of the code. Unit tests are used to test each function one at a time, and in some cases might even test just part of a function or class. @@ -14,7 +14,7 @@ This is used for multiple functions at the same time. Regression tests look at the final answer for an example input and are used to check that changes to one part of the code are not changing the overall performance. -# Code Coverage +## Code Coverage Code coverage is a metric related to how much of your code is being tested. Low code coverage suggests that there are parts of the code that may or may not contain bugs. @@ -22,3 +22,6 @@ In this case, writting more tests is recommended. High code coverage is good, but does not guarentee that all bugs have been found. Some functions might need more than one test to cover all the possible input cases. + +[Next](2_pytest.md) +[Home](../) diff --git a/code_testing/1_pytest.md b/code_testing/1_pytest.md deleted file mode 100644 index 728110c..0000000 --- a/code_testing/1_pytest.md +++ /dev/null @@ -1,9 +0,0 @@ -## Pytest - -Pytest is one example of a program used for running tests. -The documentation for pytest can be found [here](https://docs.pytest.org) - -*Activity* Change to the code_testing directory of the software workshop. -Look at the functions.py code and the test_functions.py. -Try running the test. Does it pass? if not why not and can you fix the code so that the test passes? -Does the test cover all the functionality? Try writting more tests. diff --git a/code_testing/2_pytest.md b/code_testing/2_pytest.md new file mode 100644 index 0000000..17fa701 --- /dev/null +++ b/code_testing/2_pytest.md @@ -0,0 +1,34 @@ +## Pytest + +Pytest is one example of a program used for running tests. +The documentation for pytest can be found [here](https://docs.pytest.org) +Pytest looks for files named test_* .py and within those it looks for functions named test_* and then runs all the tests it can find. + +# Installing and running pytest +You can install pytest using pip. +```bash +pip install pytest +``` +Check that it has installed +```bash +pytest --version +``` +or read the help +```bash +pytest --help +``` + +Run pytest using the command line in the file where your `test_*.py` file(s) are. +```bash +pytest +``` + + +*Activity* Change to the `code_testing/example` directory of the software workshop. +Look at the `functions.py` code and the `test_functions.py`. +Try running the tests. What happens? +Can you change the code so that all the tests pass? + +Does the test cover all the functionality? Try writting more tests. + +[Home](../) diff --git a/code_testing/__init__.py b/code_testing/example/__init__.py similarity index 100% rename from code_testing/__init__.py rename to code_testing/example/__init__.py diff --git a/code_testing/functions.py b/code_testing/example/functions.py similarity index 100% rename from code_testing/functions.py rename to code_testing/example/functions.py diff --git a/code_testing/test_functions.py b/code_testing/example/test_functions.py similarity index 100% rename from code_testing/test_functions.py rename to code_testing/example/test_functions.py diff --git a/environments/1_getting_started.md b/environments/1_getting_started.md index f5f7f4f..340c318 100644 --- a/environments/1_getting_started.md +++ b/environments/1_getting_started.md @@ -1,15 +1,15 @@ -## Enviornments +# Environments This session aims to cover some of the basics and get you started with installing software. -# Operating Systems +## Operating Systems The operating system manages the hardware and software for your machine. It allows us to manage files and install and run software. There are several flavours of operating systems; the three most common are Windows, Mac, and Linux. Linux is often used in scientific programming and on high performance computing (HPC) resources. -# Resources for Getting Started with Linux +## Resources for Getting Started with Linux If you are new to Linux here are some links to introductory material. - [YouTube video by ProgrammingKnowledge](https://www.youtube.com/watch?v=PTaL1s3YJPY&ab_channel=ProgrammingKnowledge) @@ -18,7 +18,7 @@ If you are new to Linux here are some links to introductory material. And some links for Virtual Box (to create/run virtual machines) and Windows Subsystem for Linux. - [Virtual Box](https://www.virtualbox.org/manual/UserManual.html#intro-installing) -- [Windows Subsystem for Linux](https://learn.microsoft.com/en-us/windows/wsl/setup/enviornment) +- [Windows Subsystem for Linux](https://learn.microsoft.com/en-us/windows/wsl/setup/environment) # Troubleshooting @@ -32,3 +32,7 @@ Then you can check the requirements for the program you want to install and make If the error message is telling you that it can't find things you know are installed, check the PATH variable (on Linux). You might have to add/change the PATH variable so that your operating system looks in the right place for the programs and libraries it needs. + + +[Next](2_dependencies.md) +[Home](../) diff --git a/environments/2_dependencies.md b/environments/2_dependencies.md index 50ba38f..7e21fee 100644 --- a/environments/2_dependencies.md +++ b/environments/2_dependencies.md @@ -1,11 +1,11 @@ -## Dependencies +# Dependencies When installing software, many of the challenges come from the dependencies. Dependencies are when one code uses other codes or libraries (sets of functions). The software you want won't work unless it can find all the other bits of code it depends on. Here we will look at some of the potential issues and ways to make your software installation work. -# Versions and Package Managers +## Versions and Package Managers Some software has lots of dependencies and often the software needs a particular version of the other codes. You can look in the documentation for the list of requirements and install each of them, but it is easier to use a package manager if there is one that has the software you want. @@ -16,7 +16,7 @@ Please be aware of terms of service when using Anaconda's repository (and in gen I recommend looking at the documentation for the software you want to install and following their instructions. Reading documentation is not the most exciting thing in the world, but it can be helpful. -# Environments +## Environments One thing that can make installing software tricky is when different pieces of software have conflicting dependencies. This can happen when they use different versions of a common library. @@ -56,10 +56,12 @@ conda create -n conda activate ``` -# Virtual Machines +## Virtual Machines A more extreme way of separating software is to use a virtual machine. A virtual machine has its own operating system and file system, separate to the host operating system. This can be useful, for example if you have a Windows laptop and want to run a Linux system without losing access to the Windows programs. A virtual machine will allow you to act like you have two machines and switch between them. One example is [Virtual Box](https://www.virtualbox.org) + +[Home](../) diff --git a/version_control/1_version_control.md b/version_control/1_version_control.md index 0320ca1..cc5d4c6 100644 --- a/version_control/1_version_control.md +++ b/version_control/1_version_control.md @@ -1,10 +1,10 @@ -## Version Control +# Version Control We want to be able to track changes without having multiple copies of files. We also want to be able to work with other people. Git is one of the most widely used version control tools, but others exist. -# Using Basic Git +## Using Basic Git To get a local copy of a repository: ```bash @@ -20,3 +20,6 @@ git push ``` [Cheat Sheet](https://training.github.com/downloads/github-git-cheat-sheet.pdf) + +[Next](2_git.md) +[Home](../) diff --git a/version_control/2_git.md b/version_control/2_git.md index 380a894..4e0a227 100644 --- a/version_control/2_git.md +++ b/version_control/2_git.md @@ -1,8 +1,8 @@ -## More Git +# More Git Once you learn the basics of getting a repository and comitting changes there are some slightly more advanced features of git -# Branching Models +## Branching Models A common model has several branches: - "main" branch for released/stable versions of the code @@ -24,7 +24,7 @@ git checkout ``` to change to an existing branch. -# GitHub +## GitHub [GitHub](https://github.com) is a website that hosts repositories. It uses git to interact with the repositories and allows you to "fork" or copy public repositories. @@ -37,7 +37,7 @@ See [GitHub authentication](https://docs.github.com/en/authentication/keeping-yo GitHub also has tools like a issue tracker where people can raise issues (for bugs, feature requests, or comments). The issue tracker can help you keep track of problems that have been raised and comments used for discussions. -# Activity +## Activity Create a GitHub account if you don't already have one. @@ -50,3 +50,5 @@ Alternatively, if you don't want or can't get a GitHub account, you can clone th Make a new branch and then make changes to the example code (functions.py). Can you commit and push the changes? + +[Home](../)