Skip to content

pypi_exercise.md

Latest commit

 

History

History
103 lines (76 loc) · 8.22 KB

pypi_exercise.md

File metadata and controls

103 lines (76 loc) · 8.22 KB
Raw

Exercise: Packaging Python Code

Starting remarks

  • Exercise repository link
  • Deadline for submitting this exercise is Wednesday 19th November 09:00.
  • The code in this exercise produces plots and in order to view them you need to use a GUI-based operating system or environment.
  • The exercise follows the steps in the Python packaging tutorial.

Brief idea of the exercise

In this exercise you, will convert a simple simulation code written in Python into a package that is available on TestPyPI.

Prerequisites

  • An operating system / software / environment where you can install Python and some basic Python tools.
  • An editor or IDE to edit Python code and write text files.
  • The following Python tools:

Step 1 - Acquiring the code and getting familiar with it

  • Fork the exercise repository.
  • Open the file diffusion2d.py and go through the file and try to understand it.
  • Check if your system has Python version >= 3.6 and update it if it is older than 3.6.
  • Install pip, build, and twine.
  • Install NumPy and Matplotlib with pip. The installation instructions can be found on the webpages (links in the Prerequisites section of this document).
  • Run the code by running python diffusion2d.py and observe the output. You should see four plots combined into one figure. Save this figure on your system.
  • Information about diffusion2d.py: This code solves the diffusion equation over a two dimensional square domain which is at a certain temperature, and a circular disc at its center which is at a higher temperature. The diffusion equation is solved using the finite-difference method. The thermal diffusivity and initial conditions of the system can be changed by the user. The code produces four plots at various timepoints of the simulation. The diffusion process can be clearly observed in these plots.
  • Take a few minutes to play around with parameters dx, dy and D in the solver file and observe how the value of dt and the output changes. Do you notice if the code takes more or less time to finish the computation?
  • If you are interested in the theoretical background of the code, take a look at chapter 7 of the book "Learning Scientific Programming with Python".

Step 2 - Refactoring the code

  • It is good practice to put code specific to a functionality in a separate file for better readability and sustainability.
  • Create a file output.py on the same level as diffusion2d.py.
  • Create two functions in the file output.py called create_plot() and output_plots().
    • The function create_plot() should create one plot for one time stamp. In the earlier output, this would be one of the four plots. You will find this functionality inside the time loop in diffusion2d.py.
    • The function output_plots() should output all the four plots as one figure. You will find this functionality outside of the time loop and at the end of diffusion2d.py.
  • Port the appropriate parts of the code pertaining to figure creation and figure output from diffusion2d.py into these two functions.
  • Take care to pass the appropriate arguments to both these functions and also return the correct quantities. Code refactoring should not affect the functionality, that is, the refactored code should work exactly as the original diffusion2d.py.
  • Once the functionality is ported, you need to import it into the diffusion2d.py. This is done in the following way
from output import create_plot, output_plots
  • Note that the from output command will only import functions from output.py if no global Python package with the name output exists. If another package named output exists, then a relative import needs to be done.
  • Once the output functionality has been separated from the solver, we need to bundle the solver itself into a function called solve in diffusion2d.py. We need to do this because later on we will call this function after importing the package in the following way,
from package_name import diffusion2d

diffusion2d.solve()
  • Once you have refactored the code, try calling the solve() function again through a Python script or directly in a Python shell. Compare the plots with the plots in the figure you saved earlier. Both outputs should be identical.
  • The function solve() should take in physical parameters as input arguments. In this case, change the parameters dx, dy and D such that they are passed to the solve() function by the user. Provide default values for all three of these parameters.

Step 3 - Creating folder structure for packaging

  • Now that you have a refactored code, replicate the folder structure we learned in the lecture to prepare the code for packaging.
  • As discussed in the lecture, create the configuration file pyproject.toml file, and a README.md.
  • It is recommended to have the package-name/ folder which has the source code in it. Select an appropriate package name.
  • Note: General recommendation is to have the name of the folder having the source files to be same as the name of the package as seen when imported at the time of use.
  • The README.md file consists of a longer description about the code and what it does. Take the information about the code from Step 1 of this exercise and add it to the README. In addition to this fill out the empty sections of the README with relevant information.
  • In the pyproject.toml, name your package <your-GitLab-username>_diffusion2d (the underscore _ between your GitLab username and diffusion2d is important, because any other symbol will not work). We will use semantic versioning, so the version you are developing will be 0.0.1. The package url is the url of the GitHub repository of this exercise code.
  • Try to add as many configuration options as you can.
  • Hint: Look at the guide on configuring setuptools with pyproject.toml.

Step 4 - Create build artifacts

  • Create build artifacts for this project. Use the build tool to create the build artifacts.
  • After creating the distribution packages, check the dist/ folder to ensure that the archive files have been created.
  • Important: If for some reason the package does not work and you wish to upload a changed state of the package, you have to remove all contents of dist/ before creating new build artifacts.

Step 5 - Create an account and a API Token on TestPyPI

  • Create an account on TestPyPI.
  • Create an API Token on TestPyPI.
  • Note down the name and token value because this is the username and password for publishing.
  • Copy the API Token and Password and configure it on your system in the file $HOME/.pypirc.

Step 6 - Uploading the package

  • Upload the build artifacts to TestPyPI.
  • Go to TestPyPI and view the package which has been uploaded.

Step 7 - Testing the deployed package

  • Try to install the package using pip and also run the code by importing the solve() functionality in a Python script or an interactive Python shell.
  • Even though your package is on TestPyPI, the dependencies of the package need to be installed from PyPI. To make sure that the dependencies are installed from PyPI and not TestPyPI, use the --extra-index-url option of pip.

Step 8 - Submitting the exercise

  • Open a pull request with the name Packaged code by <your-GitLab-username> from your fork to the main branch of the exercise repository.
  • Only push the refactored code, pyproject.toml, README.md, and __init__.py. Do not push the build artifacts.
  • Important: Add a link to the TestPyPI package page in the description of the pull request.