Welcome to Pythonic CS1: Build a Mobile App!¶

Strengths of Current Solution¶

1. Git and GitHub provides a platform for teachers to concurrently author the content, and have all changes versioned.
2. GitHub and ReadTheDocs works perfectly together to continously push the latest content available to the learners.
3. GitHub and ReadTheDocs are free, such that there is no cost of hosting and no server to be maintained.

Weaknesses of Current Solution¶

1. GitHub and ReadTheDocs can only host static content, which limits the interactivity of the course. As a programming class it is ideal to allow students editing and running programming quiz without leaving the course. Existing in-browser solutions are either lack of 3rd party libraries support, or requires running and maintaining expensive servers, which are not ideal to be plugged into the our current solution.
2. The current solution is web-based, and is inheriently less responsive than mobile app.

Opportunities to Improve Current Soution¶

1. Build a mobile learning app which synchronize static content from GitHub / ReadTheDocs, and run programming quizzes inside mobile device.
2. With Python and Kivy is possible to build a Python programming environment like this Android app. As the program is executed inside an Android phone, we can preload the 3rd libraries required, and the program can be run natively in an Android phone without a need of any expensive server.

With these opportunies, let’s foucs on the requirements of our mobile learning app.

Download and Install Virtual Box and Ubuntu Linux¶

1. Download and install Virtual Box.
2. Download and add Ubuntu 64 Bit Virtual Box image into your Virtual Box. Latest version is recommended. Please refer to the web site for user name and password.

Install Kivy, Git, and PIP¶

1. Start the Ubuntu. Input the username and password obtained in the last step to login. Right click desktop and choose open terminal.
2. In the terminal, run the following command:

sudo apt-get upgrade
sudo apt-get install python-kivy
sudo apt-get install git
sudo apt-get install python-pip

Intall Pycharm IDE¶

1. In your Ubuntu. Open Firefox. And download Pycharm Commnity Edition for Linux
2. By default, it would be saved at ~/Downloads.
3. Open terminal again. Type the following:

cd ~/Downloads
tar xvzf pycharm*.tar.gz
rm pycharm*.tar.gz
mv pycharm* ~/pycharm

Running PyCharm¶

1. Open terminal.
2. Run Pycharm in terminal by:

~/pycharm/bin/pycharm.sh

If PyCharm asked for Key binding / mappings, choose Eclipse for the sake of this course.

In the next section. You will learn about what you have just setup.

What is Pycharm¶

Pycharm is a Python Integrated Development Environemnt which streamlines your development, testing, debugging, and version control experience. Altnhough you can watch this Pycharm IDE Video Tutorial to see how Pycharm can help you, let’s again get the hand dirty by working out the following tutorial :)

Launching Pycharm¶

1. Open a terminal.
2. Run the following command.

~/pycharm/bin/pycharm.py

Pycharm IDE: Look and Feel¶

Your usual PyCharm setup would look like this. In short, you have a list of files in your project on the left hand side, and opened files on the right hand side. You may create / edit Python code and auto-code completion would happen like other IDEs. Alternatively, you can press CTRL-SPACE to force auto-code completion dialog to be shown if it doesn’t.

Sometimes, you may typed some code which cause compilation error. For insance, you are using a class but forget to import it into your source. Then you may try pressing ALT-ENTER and Pycharm would attempt fixing this for you.

Sometimes, you would like to override a function which has been defined in the base class. You may press ALT-INSERT to help you choosing the function which you want to override. Pycharm will then fill in the function signature for you.

Step 1: Forking a Project into Your GitHub Account¶

To get started using Git and GitHub. You need a GitHub account.

1. Create a GitHub account if you do not have one.
2. Visit Kivy Crash Course and press the Fork button.

Step 2: Clone the Forked Project into Your Machine via PyCharm IDE¶

Now you have forked a project into your GitHub account. Next step is to clone this project into your local machine. To do this:

1. Follow the steps as mentioned in here. Locate the kivycrashcourse repo to be cloned into your machine.
2. If it is successful, you should be seeing a screen like the following in step 3.

Step 3: Running Your first Kivy App¶

At this point your have setup yout PyCharm environemnt together with the Kivy Crash Course. While you may watch the video for the full crash course, you may run your own copy of Kivy app. Here is how to do it:

1. Open after.py like the screen above.
2. Press ALT-SHIFT-F10 to run the program. Note at the 1st attempt PyCharm may be processing in background such that you cannot run the app until it has finish. You can find out PyCharm’s progress by looking at the lower right corner of the screen. Be patient and run again after it has finished.
3. If you can see a new window like below, that means you have setup the things you need to start building app in PyCharm and Kivy. Well done!

Step 1: Fork the Starter Code into Your GitHub Account¶

1. Please fork from this URL. Please refer to the previous sections if you are not sure how to do it.

Step 2: Clone to PyCharm¶

1. Like what we did previously. Please refer to the previous document for details.

Step 3: Switch to 0.1.0 Branch¶

Please type the following. We will explain why we need to do that in the next module :)

git checkout release/0.1.0

Step 4: Run the Starter Code¶

1. By locating main.py and run it. You should see a screen like this:

Let’s discuss this screen in details in the next section.

Questions / Exercise for You¶

1. Which function will be triggered when you click on a ref? Can you add a watch to look at the variable “value”?
2. Which function will be triggered when you click on the Home button? How about the Up button and the Next button?
3. Open course.kv. Based on the experience from the first 2 points, can you locate how does event bindings are defined in Kivy Language?
4. Additional reading: Kivy Events and Properties

Next Steps¶

Well done. Now you have learnt a lot how to get started in PyCharm to develop our mobile learning app. In the next modules, you will learn how to add additional functionalities into our app. You will start writing some Python code to make the app to be even better. Stay tuned :)

Steps¶

Let’s demostrate the first step by creating a new feature branch from master. First I will type the following from my terminal

cd <<your git clone folder>>
git checkout master
git pull
git checkout -b feature/hyperlink

The command above will:

1. Get the latest code from master
2. Create a new feature branch from master, namely feature/hyperlink.

I can verify I am in my feature branch by typing:

git branch

It will highlight my current branch.

Why a Feature Branch¶

The followings are reasons why we make a feature branch from master:

1. It allows me to develop my feature without impacting the others.
2. It allows me to select a right moment, where my changes are ready and tested, to be integrated into master with other people changes to collectively make a new release.

Discussions¶

1. Note the arrangement above is just one possible way of branching. As our project is simple we choose simple model.
2. You may watch this video for some other advanced branching models.

What is and Why Unit Test¶

Unit test and unit testing are important concepts and activities that help us to write high quality code with productivity. Let’s highlight the folowing advantages:

1. It allows part of our program to be test independently from ther others, hence helping us to focus on what we are testing.
2. Unit testing can be automated, hence giving us a ability of testing our program automatically.
3. It allows us to accumulate a suite of test cases. Imagine if I develop my feature with its corresponding test cases and you also do the same. Collectively we can test the different features of the program automatically.

Understanding Requirements¶

Let’s demostrate how to add a Unit to test the feature I am building, i.e. support of external hyperlink. Let’s understand the requirements:

As you can see above, hyperlinks are not displayed properly in the screen. We would like to add support for hyperlink such that:

1. We would read the page line-by-line, and replace all `link description <link>`_ patterns such that they are instead become [ref=link]link description[/ref]. For example, the above link should be presented as [ref=https://en.wikipedia.org/wiki/Unit_testing]unit testing[/ref].
2. There can be 1 or more hyperlink within single line. Each of them should be handled accordingly.
3. Once clicked, a web browser should be launched to display the corresponding web page.

Let’s add a Unit Test for parsing and formatting the hyperlink as required above. We will leave launching a web browser to be done in the next module.

Adding Unit Test with Pycharm¶

1. Add a method format_hyperlink(self, line) inside CourseApp class. For now, let’s simply add return line as its implementation.
2. Add a file test_CourseApp.py. It should look like this. Press ALT-SHIFT-10 to run it.

As you can see. Pycharm will show you how many test cases are you passing / failing. In this case, as we haven’t implement anything yet in our format_hyperlink(self, line) function, it is expected that we have failing cases. Here we are demostrating one important feature on how unit test can be used to drive our development effort that:

1. Before startng writing code, write test which fail first.
2. Make change to pass tests.
3. Repeat until you have passed all tests.

In later modules, you will see how we make use of unit testing to not just improve the correctness of our code, but also improve the quality of our code. We collectively call this effort a Test-driven Development (TDD) methdology. For now, let’s focus on writing code to passes all of our test cases first.

Implementing the Function to Pass the Tests¶

Let’s try implementing the function like the following:

def format_hyperlink(self, line):
  return re.sub('`(.*) <([^>]*)>`_', r'[ref=\2]\1[/ref]', line)

And run the test again. This time we have passed 2 cases, but leaving 1 case failing:

Now let’s fix our code to be the following:

def format_hyperlink(self, line):
  return re.sub('`([^`]*) <([^>]*)>`_', r'[ref=\2]\1[/ref]', line)

And run the test again. This time we have passed all tests. Cool!

Discussion¶

1. In the implementation above, we are using Regular Expression module to help us extracting information from a pattern and replacing the matching pattern with the re-formatted information that was extracted previously. You may check out this video for a tutorial.
2. Once you have finished, in your own word, can you explain what does teh regular expression do which passes all the tests?
3. Then, in your own word, can you explain why the first attempt does not work for more than 1 hyperlink?

Seeing the New Feature¶

So now my feature looks good. I can intrgrate my change to see it in shot:

Next¶

Next, let’s integrate my change back to master.

Creating and Merging Pull Request¶

Pull request allows your teammates to review our change before it is merged into the master. Here are some links for background understanding on how does it work:

1. About Pull Request
2. Creating a Pull Request
3. Merging Pull Request
4. Our Pull Request

Next¶

Let’s make a new release 0.2.0 as a next step.

Step 1: Install Buildozer¶

sudo pip install buildozer
sudo dpkg --add-architecture i386
sudo apt-get update
sudo apt-get install build-essential ccache git libncurses5:i386 libstdc++6:i386 libgtk2.0-0:i386 libpangox-1.0-0:i386 libpangoxft-1.0-0:i386 libidn11:i386 python2.7 python2.7-dev openjdk-8-jdk unzip zlib1g-dev zlib1g:i386

Step 2: Setup Buildozer for Our Mobile App¶

cd <your app folder>
buildozer init
vi buildozer.spec

This will open the buildozer.spec file. You may change permission / libraries needed in here. Click here for details.

Step 3: Run Buildozer¶

buildozer -v android debug

This will start the compilation. The first run will take long as it will download Android SDK and Android NDK. The subsquent run will be much faster.

Once the complication is done you should be able to see an apk file in <your app dir>/bin folder. You may use upload this file into your Google Drive and download it into your phone. Click on the APK file to install. If you ask for permission, grant it and it should complete the installation.

Step 4: Upload to Google Play Store (optional)¶

Click here for details. This step is optional as you need to pay google momey to do it :)

Additional Resources¶

1. Kivy Crash Course: Buildozer
2. Android Permissions