diff --git a/README.md b/README.md index f1dca2970b2b9249054517aa05991a9986ee489b..18c56dcd3181f55cd596b2fbe666a029237924bd 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,6 @@ -***!!Replace this readme with a description of your project as soon as possible!!*** +ββ Replace this readme with a description of your project as soon as possible ββ -# python-template-1 +# python-template-mini Hi! This is a minimal template for Python projects. The main purpose of the template is to help you to organize your code in a nice way. However, it is not intended to teach you how to write good code. @@ -8,6 +8,16 @@ That part is up to you :) The code included in this repository is in itself a small tutorial on how to structure your python code. +### Python templates + +<!-- <span style="font-size: 12pt; font-weight: bold;"> --> +| | link | Focus | +|:------:|:----:|-----------------------------------| +| π | [Mini](https://github.com/adraismawur/python-template-mini) | File and code structure | +| ππ | [Midi](https://github.com/adraismawur/python-template-midi) | Requirements and packaging | +| πππ | [Maxi](https://github.com/adraismawur/python-template-maxi) | Automatic formatting and checks | +<!-- </span> --> + ### Table of contents: @@ -19,47 +29,37 @@ The code included in this repository is in itself a small tutorial on how to str ### Prerequisites -- A package/environment manager (e.g. [MiniConda](https://docs.conda.io/en/latest/miniconda.html)) -- Git +β This template assumes you have installed and are somewhat familiar with: -### Download the files +- [Git (https://git-scm.com/)](https://git-scm.com/) + You should know how to add (stage) files, remove (unstage) files, commit, push and pull +- Python version 3 + Any version marked 3.x.x is okay. + If you are not sure what version of python is installed, run ```python --version``` in a terminal window. + +### Set up the repository (local only) + +βChoose this if you are just starting out, or if you do not want to create a page on Github for your code. 1. On this GitHub page, click the **Code** dropdown button in the top-right 2. Click Download ZIP 3. Extract the files somewhere in a new directory - -### Set up the repository (local only) - -1. Open a shell in the directory where you have extracted the files -2. Create a [virtual environment](#why-do-i-need-an-environment-manager) using an environment manager. - One convenient program is [MiniConda](https://docs.conda.io/en/latest/miniconda.html) -3. Assuming that you have (Mini)Conda installed, create a virtual environment: `conda create --name your_project_name python=3.11` -4. Enter the newly created environment with `conda activate your_project_name`. - The prefix of the command prompt should switch to `(your_project_name)` to show the change in environment. - If you need to leave the environment, do `conda deactivate` -5. Run `git init` to initialize the git repository -6. Edit the `pyproject.toml` file to add metadata on your project -7. Install your project in the virtual environment using `pip install -e .`. - This will also install all packages/dependencies you may have listed in your `requirements.txt` file. -8. Run `pre-commit install` (installed by the previous command) to set up pre-commit -9. Edit the readme file to describe your project -10. Run `git add .` to stage all files -11. Run `Git commit -m "initial commit"` to make your first commit - -This process ensures that the history of your repository is clean, and not tied to this GitHub repository in any way. +4. Open a shell in the directory where you have extracted the files +5. Edit the readme file to describe your project +6. Run `git add .` to stage all files +7. Run `Git commit -m "initial commit"` to make your first commit ### Set up a remote repository (on GitHub) -1. Create a new repository of your own by going through the plus icon in the top right -> new repository. - Or [click here](https://github.com/new) +βChoose this if you want to ensure your code is always saved online, or if you want to share your code. + +1. Create a new repository of your own by pressing the green button in the top right named "use this template" -> Create a new repository. + Or [click here](https://github.com/new?template_name=python-template-mini&template_owner=adraismawur) 2. Give your repository a nice name and description -3. Under the section "**Initialize this repository with**", do not add anything. -4. You are now presented with a few steps you can take. You can follow those under the section "**β¦or push an existing repository from the command line**": -```bash -git remote add origin git@github.com:[your_username]/[your_repository].git -git branch -M main -git push -u origin main -``` +3. Choose whether you want the repository to be public (anyone can see your code), or private. +4. Press "Create repository" + +You will be taken to your own github page after a few seconds. ### Start coding! @@ -79,32 +79,12 @@ It's difficult to write code. It can be even more difficult to write code that is easy to read and maintain. This template is designed to help you structure your python code in a way that is common for a lot of well-maintained Python projects, while not forcing any of the more difficult aspects of code mainenance on you. -### An environment manager - -Almost every Python program you write uses external modules/packages (e.g. Pandas, Numpy). -These external programs are under constant development and come in different versions. -Different programs may use different versions of the same module/package. -For example Project_A uses pandas v1.8.0, while Project_B uses pandas v2.1.0. -However, having multiple versions of the same program installed on your computer may lead to errors and general confusion. - -This problem is solved with virtual environments: these represent "folders" in which specific versions of programs can be installed. -For example, Project_A would have pandas v1.8.0 installed in its virtual environment, while Project_B would have pandas v2.1.0. - -Virtual environments can also be easily removed after they are not needed anymore (including all the packages that they contain). -This allows to keep your computer (the so-called base environment) clean. -Several environment managers are available. -One example is Conda (or its lightweight version, MiniConda), which is widely used. -More information on virtual environments can be found [here](https://realpython.com/python-virtual-environments-a-primer/). - - ## What is included in this repository? - A [README](#a-readme-file) file - A (copyleft) [license](#a-license) - A basic [folder structure](#folder-structure) -- A [requirements.txt](#requirementstxt-file) file with essential packages -- [Pre-commit](#pre-commit), using: - - [Black](#black) +- A .gitignore file ### A README file @@ -138,35 +118,15 @@ It takes people very long to read through an entire file to find the specific co If you are working with just a few functions, it is also OK to have a few python files in the root directory without any subdirectories. -### `requirements.txt` file - -A requirements file makes it easy for people to automatically install the same dependencies you used to develop and run your application. -You can also fix your requirements to specific version numbers to ensure that people can use the exact same dependencies and re-produce your work. - -### pre-commit - -[pre-commit](https://pre-commit.com/), a Git [hook](https://git-scm.com/book/en/v2/Customizing-Git-Git-Hooks) added to this repository ensures a basic level of code style and prevents some minor issues. -As the name implies, scripts configured in the hook will be run before attempting to commit changes to your (local) repository. -Since you (hopefully) commit early and often, pre-commit ensures that your code remains nicely stylized and readable. - -Here, the only script pre-configured for pre-commit is Black. - -### Black - -[Black](https://github.com/psf/black) is a code formatter. -Any code base that uses it will have a style that is the same no matter who wrote the code. -A consistent code style makes it easier to read, maintain and expand on code. - -#### Why does Black use spaces instead of tabs? - -Pretty much all of Black's choices come from adhering to the [PEP8 Style guide](https://peps.python.org/pep-0008/). - -Wherever it does not, the authors have made their own decisions and are just applying them consistently. - -#### Why does Black limit lines to 88 characters? +### .gitignore -PEP8 [recommends 79](https://peps.python.org/pep-0008/#maximum-line-length), but Black extends it to reduce average lines of code. +When writing code, it is common that you create large, temporary or otherwise unimportant files that you do not want to add to your repository. -Additional context: 79 is a historical choice (small monitors could commonly support about 80 characters) as well as a practical one; Using a small character limit ensures that you can put multiple files next to each other on common screen sizes, which really helps in comparing files. +Instead of having to select what you want to add or do not want to add to a commit, you can use this file to specify what files you want to ignore when making changes to your code. +Git ignores any file that matches a line written in the .gitignore file. +The asterisk (*) can be used as a wildcard to include any random text. +The double asterisk (**) is used to search recursively through folders, meaning it will go through all folders and subfolders based on a path. +The .gitignore file that is included in this directory was automatically generated by GitHub to include all common files generated in python projects. +Feel free to play around with this file, or replace it with your own needs if necessary.