Skip to content

For Developers

About This Page

This page is meant for any developer who wants to set up this project on their machine in order to develop or to test something. If you are the end-user of this package and want to use the package directly as an asset, please visit Home to know on the installation instructions.

Cloning The Repo 🔑

  • This project is available at a GitHub Repo called as pyconceptlibraryclient.

  • To clone the repo - You can either use your IDE specific Git GUI interface or you can use that boring Terminal of yours.

    • If you are using your IDE specific Git GUI, please refer to the IDE's docs for reference. I was using VScode for my development purposes, hence you can find some help for it, here.

    • If you are using the terminal, please go to the desired folder in your machine where you want to have this project set up. Once you are there, please run the following command : 

      git clone https://github.com/SwanseaUniversityMedical/pyconceptlibraryclient.git

  • Once cloned successfully, open the project in your IDE.

Spinning up the Development Environment 🛠️

  • This python project uses Poetry for dependency and package management. You will see pyproject.toml file in this project which consists of the information about this project (name, version, dependencies, etc).

  • To start off, please type this command in the terminal (in your project root directory, obviously): 

    poetry install

  • This command will install all the dependencies that are listed in the pyproject.toml file.

  • To start off running any script, we have to run the following command in the terminal: 

    poetry shell

  • This will spawn up a virtual environment for your project (uses Python 3.11 as per pyproject.toml file of this project), which you can use for carrying out your development chores.

  • I wanna know more about Poetry

  • And this is pretty much it 🥸 Go create history now!

Project Structure 🎁

  • .github: This folder consists of our github workflows. You may add your own as per your needs.

  • .venv: This folder is generated by Poetry after running poetry install.

  • docs: This folder consists of the .md files generated by Mkdocs. More on this somewhere below.

  • test: Should consist of the test files. If not, you are welcome to add any unit tests. But I think, you might want to add pytest before you run your tests. (Tip: Run poetry add pytest)

  • pyconceptlibraryclient: Meat and Starting point of this project. Here, you will find the code concerning the interaction with the API server and handling the response.

Building the Package 💽

  • Poetry got you covered here as well 👽 Just run the following command in your terminal: 
    poetry build

  • This will generate a dist folder in your project root directory. It should consists of two entities with .whl and .tar.gz extension.

  • The entity with .tar.gz is basically your package that you will publish to either your GitHub Release Notes or to PyPI.

  • In our team, we are not publishing to PyPI. We are just using Github for our internal use.

Updating this doc website 🖨️

  • The first thing is to keep in mind that docs are automatically generated from the docstrings of the methods inside the main folder of the package; thanks to Mkdocs.

  • Just update the docstrings, and the content should be updated.

  • Let's say you updated a few docstrings, now what? Run the following commands as given below (given that you are inside your virtual env, obviously): 

    mkdocs build

    mkdocs serve

  • Just open your localhost if commands above, don't throw any error.

  • I still need help on configuration.

  1. Please raise a pull request with proper naming as exemplified below:

    • feature/<your-feature-in-short>: If you are contributing anything new.
    • hotfix/<argh-this-silly-mistake>: If you missed a bracket or a pair here and there.
    • bugfix/<that-dev-is-having-a-bad-day>: If something significant is breaking the whole project or a significant part of it.

  2. Although, this project has a github hook for formatting the code with Black, BUT its good if things are kept clean and readable.

  3. Avoid force pushes as much as possible.

  4. Avoid dirty commits - meaning that, commit for a single purpose. Dont put commit message 'changes to A' while having both, A and B changed. Keep segregating your commits, thats a good practice.

  5. Avoid too much coffee, sleep well! 😴

Hope you have fun, Cheers!