In Python

A simple package (module) in Python is simply a directory with a Python file in it. In Colab, this code will create a directory and a Python file containing a Hello World example:

! mkdir -p MyPackage
! echo "def helloworld():" > MyPackage/helloworld.py
! echo "    print('hello world')" >> MyPackage/helloworld.py

Now we can directly make use of our new helloworld() function in Python:

import MyPackage.helloworld as mphw

mphw.helloworld()

In the import name, MyPackage is the name of the directory, and helloworld is the name of the file. We rename MyPackage.helloworld to mphw for brevity, but it’s optional.

Well, that was easy!

Though our package is technically not a complete package yet, as it can only be run if we copy the file to every code project that wants to use our function. A true package can be installed and then run from any place on your computer. Thankfully that’s also easy to do! All we need is to provide a bit more structure and metadata.

The metadata file in Python is called pyproject.toml, and it has to be in a subdirectory with the name of the package, as the name will appear in the list of packages. The actual functions need to be in a subdirectory of that subdirectory, with the name of the package, as the package will appear in Python. Typically, both of these names should be the same, otherwise it will result in user confusion. Lastly, if we want to be able to just import the package to get our functions, without having to specify the name of the file that holds the functions we want to import, we should call the script with our functions __init__.py.

In summary, the package structure looks like this:

MyPackage
├── MyPackage
│   └── __init__.py
└── pyproject.toml

Let’s make our files match this structure! First, make the subdirectory MyPackage/MyPackage, and then rename our helloworld.py to MyPackage/MyPackage/__init__.py:

! mkdir MyPackage/MyPackage
! mv MyPackage/helloworld.py MyPackage/MyPackage/__init__.py

Next, let’s add the project metadata. We only need to specify the name of the package and its version. To prevent confusion, use the same name as the name of the two directories.

! echo '[project]' > MyPackage/pyproject.toml
! echo 'name = "MyPackage"' >> MyPackage/pyproject.toml
! echo 'version = "0.1"' >> MyPackage/pyproject.toml

Bam, we now have a true package! We can install it with pip:

! pip install ./MyPackage

And now we can use our function from any directory simply as:

import MyPackage

MyPackage.helloworld()

In R

Packages in R are also nothing more than an organised collection of R scripts. Compared to Python, there are a few more files necessary to make an R package, but thankfully, we also have tools that help to create one!

Once again, let’s make a Hello World function and put it into a file:

echo 'HelloWorld <- function() print("Hello world")' > HelloWorld.r

Let’s make it into a package! We use the function package.skeleton() to autocreate a package structure:

package.skeleton(name = "MyPackage", code_files = "HelloWorld.r")

## Creating directories ...

## Creating DESCRIPTION ...

## Creating NAMESPACE ...

## Creating Read-and-delete-me ...

## Copying code files ...

## Making help files ...

## Done.

## Further steps are described in './MyPackage/Read-and-delete-me'.

Let’s follow the instructions to read the file MyPackage/Read-and-delete-me. And then delete it:

rm MyPackage/Read-and-delete-me

Let’s see what is the R package structure:

tree -n MyPackage

## MyPackage
## ├── DESCRIPTION
## ├── NAMESPACE
## ├── R
## │   └── HelloWorld.r
## └── man
##     ├── HelloWorld.Rd
##     └── MyPackage-package.Rd
## 
## 3 directories, 5 files

It’s a little bit more complicated than Python, but not by much. The script files are stored in a directory called R (as R packages can also include C++ code etc.), and our script file is already there. Next we have the DESCRIPTION file, which, like the pyproject.toml file we saw for Python, includes metadata about the package. You can open it and edit it. Lastly, we have the NAMESPACE file, which states which functions will be accessible to package users (as opposed to only internal to the package), and a man directory, which includes the documentation manual entries. We have two entries: HelloWorld.Rd, which is the description of our HelloWorld function, and MyPackage-package.Rd, which is a description of the package itself. These documentation files are written in an R variant of LaTeX.

Let’s install our package! First we need to build it, from the terminal:

R CMD build MyPackage

## * checking for file ‘MyPackage/DESCRIPTION’ ... OK
## * preparing ‘MyPackage’:
## * checking DESCRIPTION meta-information ... OK
## * installing the package to process help pages
## * saving partial Rd database
## * checking for LF line-endings in source and make files and shell scripts
## * checking for empty or unneeded directories
## * building ‘MyPackage_1.0.tar.gz’

As you can see, the package is just a zip of our package files, plus some metadata cache. Now we can use R itself to install our new package:

install.packages("./MyPackage_1.0.tar.gz")

## Installing package into '/home/dainius/R/x86_64-suse-linux-gnu-library/4.5'
## (as 'lib' is unspecified)

## inferring 'repos = NULL' from 'pkgs'

Perfect, we can immediately load it and use it:

library(MyPackage)

HelloWorld()

## [1] "Hello world"

As a bonus, we can also see the documentation we had in the man files:

?HelloWorld

That was also pretty easy!

To summarise, we have learned that packages in both Python and R are nothing more than scripts that contain functions, in a particular directory structure. If we start developing our projects with that structure in mind, we can make packages out of our scripts very easily!

Project structure

Making packages is a great way to stay organized, keep track of what you are doing and be able to use it quickly and properly at any time. Packages are:

• Easy to share with others
• Dependencies are automatically imported and functions are sourced (reduces the risk of having broken dependencies)
• Documentation is attached to the functions and cannot be lost (or forgotten)

For these reasons, if you build a package, next year you will still be able to run the functions you wrote yesterday. Which is often not the case for stand alone functions that are poorly documented and may depend on many other functions … that you cannot find any more. So to summarize, packages are not only a way to extend functionality, they are also the standard way to archive and save functions.

To make it easy for you to make a package out of your code, you need to stick with a project structure that packages have. Another benefit of maintaining a consistent project structure is that it will make it easier for you to switch from one project to the other and immediately understand how things work.