Wikileaks Vault 7: CIA Tips for Git Workflow

Wikileaks has begun dumping a large number of files on the CIA's hacking tools. The dump is called Vault 7. It is a goldmine, not only for information about the CIA's activities, but also for information on things like how to set up a development environment or properly use Git in your everyday programming workflow. Here are a couple highlights from some cursory searches of the document dump:

CIA Git Tutorials

CIA Vim Tutorials

CIA Setting Up a Development Environment

Comments (11)

Tutorial: Introduction to SpriteKit in Swift

(Image courtesy
This is an introduction to a series of SpriteKit tutorials written in the Swift programming language. (We will release the entire series over the course of several weeks). At the top level, this tutorial will be broken up into seven sections. Each section will be comprised of several lessons. For our first section we will focus on the fundamental techniques for working with SpriteKit content. Since sprites are the fundamental building blocks used to create the majority of a games scene’s content we will look at that next. We will then learn how to apply actions to sprites to be able to move around in a game scene. In section four we will expand on the basic concepts just learned by delving deeper into the concept of a node tree and ways to build our game scenes. We will then look at advanced scene processing techniques. In the sixth section we will learn how to simulate physics on the bodies within our scenes. And lastly we will discuss SpriteKit best practices.

Target Audience
We assume that you are already familiar with the fundamentals of app development. You should know how to develop apps using Xcode with Objective-C or Swift programming language, be familiar with blocks or closures and possess an understanding of views and windows as they relate to app development. If you are not familiar with these concepts then we suggest you visit our online learning page and go through some of our Swift programming tutorial before continuing.

SpriteKit Overview
SpriteKit is a graphics rendering and animation framework that comes with a set of tools for animating textured images, or sprites and special effects. SpriteKit conforms to the traditional rendering loop of first processing the content before the frame is rendered. This process of rendering frames is efficient because the work is executed using the graphics hardware (GPU) as opposed to using the CPU. This means that when we position sprites we can arbitrarily do so in each frame of animation without generally needing to worry about time or space complexity. In a nutshell, SpriteKit is a cross-platform (OSX and iOS), efficient and fully optimized game engine.

For the remainder of this introduction we will briefly describe some of the components used to make games. In future tutorial we will explore these and other components in greater detail.
Drawing Canvas
An SKView is an object that is responsible for animating and rendering your content once it is placed inside a window object. You may combine the content of this view object with other views that are in the same view hierarchy.

Canvas Content
SpriteKit supports different types of content that include the following:
  1.  Textured or untextured sprites. Sprites are bitmap objects that are drawn on a screen. Texturing is the processes of adding bitmap image(s) to a sprite so that our games "feel" and look lifelike.
  2. Text
  3. CGPath-based shapes. Similar to sprites, CGPath-based shapes are drawn to a screen using points, lines or arcs and may be filled with solid or gradient colors. 
  4. You may also embed video content in a game scene.
Game Scene
An SKScene is an object designed to organize the various sprites and other content within a game. Your game will present one scene at any given time. The processing logic that updates a scene on a per-frame basis will live within this object.

Game Scene Transitions
An SKTransition is an object used for transitioning between multiple SKScene objects when using a single SKView. This object provides default scene transition behavior.

Building Block
The fundamental building block of SpriteKit content are comprised of SKNode objects. These objects come with default behavior that is shared among other node objects. The SKNode class does not draw anything, but instead holds an objects position in a given coordinate system and applies any properties, like rotation, to its content and to the content of its descendants. These descendant relations of nodes are defined by their position in a tree like structure with the scene object acting as the root node. Another benefit to using the SKNode class is that it handles application events like touches. Default event handling by SKNode objects is possible because it is a subclass of the UIResponder class.

Game Action
Animation of content is achieved with the use of SKAction objects. You would generally use actions to move, scale, rotate or animate the transparency of a node. Scenes can also take advantage of these action objects.

Game Physics
SpriteKit comes with a set of objects that define how node objects interact during a collision, under the influence of gravity or in a river stream. These physics objects will speed up your game development by shifting your focus on game dynamics and user interactions instead of getting bogged down with formulating and managing physics equations. To take advantage of these physics objects, you create SKPhysicsBody object and attach them to the nodes in your scene. You can also apply gravity to all, (or some with the use of SKFieldNode), object nodes in your scene by creating a SKPhysicsWorld object and attach it to your scene. If your game includes an animating train, then you can connect the train cars with an SKPhysicsJoint object and simply move the lead car to give it a super real effect.

This concludes our introduction to SpriteKit. After reading this I hope that you are convinced that SpriteKit offers a set of tools that will help you build games comparable to that of a midsize game shop but with the use of third party tools. If you are not convinced, then stay tuned because SpriteKit offers so much more.

In our next blog post we will write code with a focus on the fundamental techniques for working with SpriteKit content.

This tutorial is based on Apple's SpriteKit Programming Guide.

Comments (1)

PyGest: A Python tkinter Tutorial, Conclusion

This is the final article in our Python tkinter tutorial series. If you've been following along from the beginning, you should now have a desktop file hashing application with a fully functioning graphical user interface!  Here is our final product:

Here is what it looks like after successfully matching a user-supplied hash value:

And here it is on failure:
We covered a lot of ground in this tutorial. We took a pretty close look at: 1) tkinter's grid geometry management system, 2) all the most basic widgets such as labels, text entry objects, buttons, etc. and even 3) some of the newer advanced features in tkinter, such as the file dialog functionality.

For the above screen shots, I obviously cleaned up the code a bit from where we left off in the previous article, having removed the various background colors we were using for debugging purposes and some other small clean up tasks (I used one of the latter to reposition the "Hash Value" and "Result" fields, see if you can find it). Here is the final state of our code:

We hope you enjoyed the series. As always, comments, questions, suggestions and critique are welcome below.

PyGest: A Python Tkinter Tutorial, Part 5

This is part five in our Python tkinter tutorial series, in which we are building a simple GUI app to process and check file hash digests. In the previous two articles (part 3 and part 4), we configured the input and output widgets for our app. In this post, we're going to build out our app's two primary buttons and hook them into the appropriate input and output fields.

Our mockup design calls for two buttons: 1) a button that computes the hash value of the given file and checks to see if it matches the value that can be provided by the user; and 2) a button that clears all the input and output fields. Before we begin, let's consider more precisely what exactly our buttons will do. For the purposes of this tutorial, we're not going to consider all the possible edge cases, but rather try to keep things simple.

When the user clicks the hash button, what needs to happen? The app should first: 1) grab the file path from the file path input field, 2) grab the hash value to check against if the user has supplied one, 3) determine which hash function to run from the user's choice of radio button. Then it has to hash the appropriate file, and when the hash digest value is returned, it should: 1) compare that value against the user supplied hash value if there was one, 2) display the digest value in the appropriate output field, 3) indicate whether there was a match, or no match, or something else, in the result field. The second button is much simpler. When the user clicks the clear button, all input and output fields should be cleared of any values.

You can find the current state of our code at the end of part four in our tkinter series. As usual, we'll begin here by getting the preliminary configuration of our button widget frame out of the way. Here's the relevant code from our View class:

Following our normal work flow, we've configured a new row in our main_frame to hold the new frame for our button widgets, and given it a weight of 1. We've also created a new method where we'll configure the frame for our button widgets, and we've called that method from our setup method. We've embedded the buttons frame into the main frame grid at row 3, column 0. And finally, we configured our button frame to have 2 rows and 1 column, to hold each of our two buttons. Let's now configure our two buttons and create place holders for the functions they will call.

These are the first buttons we've configured for our app, but the code in the snippet above should look fairly familiar to you by now if you've been following along from the beginning. We've attached each button to the buttons_frame object. We've embedded the hash button at row 0, column 0, and the clear button at row 1, column 1. We've given both a 'raised' relief to make them look like buttons, and made them both sticky in all four directions.

The only thing really new that we're encountering in the configuration of the buttons is the 'command' keyword argument. As you might have guessed, the command keyword argument contains a reference to the method that is called when the button is pressed. (Note that there are no parentheses () following the name of a method or function when it is assigned to the command keyword argument, but rather just the name of the method itself.) We've also created an initial version of each of these methods, which, for the time being, log a simple message when the method is called.

If you run the app, you'll see that each time you click one of the two buttons, the corresponding log message will appear in your terminal. Make sure you have verified this and that your buttons are working properly before moving on to the next section.

The Home Stretch
We're in the home stretch! All the widgets for our application's GUI are now in place. All that remains to do is to fill out the runHash() and clear() methods with the necessary functionality, and then clean up the code.

So, what do we need in order to run our hash function? To begin with, we need to know the full path of the file to be hashed and the hash function we are going to use. Fortunately, we have access to the appropriate class instance attributes that we created in previous installments!

In the runHash() method, we've now grabbed the file path and hash function values from their respective class instance attributes and logged the results to make sure things are working properly. If you run the app, you can play around with various input states to make sure you are indeed grabbing the correct values. Try choosing a couple different files, using the two different radio button options, and verify that the correct values are logged in your terminal.

We'll now write a top level function to process our file hashes and return the hash digest. I've decided to place this function outside our class to keep its logic separate from our app's main view. We'll name this function processDigest() and call it from the runHash() method and log the result.

If you've never used Python's hashlib module before, it might not be entirely clear what's going on in the function above. If so, don't worry too much about it, the code above should work for you, but you should read up on hashlib in the docs, and elsewhere, such as at Python Module of the Week. Suffice it to say, our processDigest() function takes two parameters: the path of the file, and the type of hash to run. It calls the appropriate hash function from hashlib based on the hash_type parameter, and then runs that function on the file located at the path parameter. If something goes wrong, it logs the error. If all goes well, it returns the hash digest.

Our hash button now returns the input file's hash value and logs it in the terminal. We still have to display the returned value in the digest output field, check this returned value against the one that may have been supplied by the user, and provide an appropriate message in the result field depending on the outcome of the match check. This might sound like a lot, but it can easily be accomplished without ever leaving the runHash method. Let's add the necessary functionality.

This seems to do the trick. First we set the hash value attribute with the returned digest string (we then get that value and log it to make sure it's there!). Then we get the the contents of the user supplied hash value input field in the same way, using the get() method that complements the object's set() method. If there's nothing there, we display a simple message saying we're done. If, on the other hand, the user supplied value matches our digest, we display a success message. And finally, on the third hand, if the supplied value does not match, we display a failure message.

Let's fill out our clear method now. It is pretty simple. All it needs to do is set our string variables to the empty string and delete the contents of our entry fields. 

Set and delete are all we need here. We've seen the set method before. Here we clear the string variables by setting them to the empty string. For the entry fields, we use the delete method. We want to delete everything in the entry field, so we pass in two parameters: 0, which is where we want to begin deleting from, and 'end', which is where we want to delete to. Here's what the app currently looks like on my system, with all the debug and testing colors still in place, after having successfully processed a hash a confirmed a match:
And that's it! All the necessary functionality for our PyGest checksum checker is in place! Our app is still a bit rough around the edges and could use some cleaning up. But everything's there and it appears to offer all the functionality required from our design and specs. In the final article in tkinter tutorial series, we'll clean up the code a bit, and then consider some final thoughts. Here's the current state of our code:

Thanks for following along!

PyGest: A Python Tkinter Tutorial, Part 4

This article is part four in our ongoing Python tkinter tutorial series. When we left off in part three, we had just completed configuring the inputs for our interface, which included text entry, label and button widgets. We'll now move on to the widgets necessary for conveying the application's two outputs: 1) the hash digest value of the file input supplied by the user, and 2) a message indicating whether the file hash generated by the app matches the optional hash value that may be supplied by the user.

In our mockup design for the application's interface, the output-related objects are comprised of four different widgets, all of which are basically just labels: 1) a pair for the output value of the digest that results from hashing the input file, and 2) a pair indicating whether that hash digest matches the optional input value that may be supplied by the user. Since the output values are going to be dynamically generated, we're also going to need two tkinter string variable objects to grab and display the dynamic values.

However, we have to be a bit careful here. If you run your app as-is, where we left off in the previous article, you'll notice that you are not able to copy the text from any of the labels we've already configured for the app. This is simply not possible because of the nature of Python tkinter labels. But it would obviously be nice if users were able to copy the output digest of the hash function. Indeed, most users would probably expect they would be able to do so, and would be annoyed if they couldn't. For this reason, we are going to use an Entry widget styled to look like a label for the hash value output, since you can copy text from an Entry widget.

To configure our output widgets, we're going to follow much the same method as we used for our inputs. We'll create an outputs frame embedded in the main frame, and then drop the various output widgets in the output frame's grid. Following our usual process, let's create a method to configure our output widgets, configure a new row to hold the outputs frame in the main frame, and call the configure outputs method from our setup method. Here is the relevant code from our View class:

This should all look pretty familiar by now. Notice, we have embedded the outputs frame at row 2, column 0 in the main frame since the inputs frame is in row 1 column 0 and the banner is in row 0 column 0. We've also given it some basic styling so we know where it is, and made it sticky in all four directions.

Our outputs frame is going to have two columns (one for a label indicating the name of the output, and one for displaying the output itself) and two rows (one for the hash digest output, and one for the result message indicating whether there is a match). Let's define them now, giving each a weight of 1.

Taking a stab at the top row of outputs, we'll need: 1)  a label to indicate to the user that she is looking at the output hash digest value, 2) a string variable to hold the hash digest value, and 3) an entry widget to provide a selectable display of the value. 

In the snippet above, we've configured a simple label indicating the result, and put it in the top left cell of the output frame grid (row 0, column 0), and provided it with the text 'Hash Value:'. We've also made it sticky to the east, so the text is displayed just to the left of the entry field. Next, we've created a string variable to hold the hash value itself, and provided it with a default text string. Notice that we've assigned this string variable to a class instance attribute because we are going to have to access it from other methods so we can get it and set it dynamically. Finally, we've configured an Entry widget to be 'readonly', with a flat relief and no highlight thickness. This latter configuration ensures that its displayed text will look like that of a label (at least on my system!). We've embedded it at row 0, column 1 in the outputs frame grid, and made it sticky to the west so it hugs its corresponding indicator label. We've further made the Entry object a class instance attribute so we can access it from other class methods as necessary. (Note: you may have to toggle the state of this Entry widget from 'readonly' to 'normal' when you want to insert a new text variable string. I have seen inconsistent information in this regard, but this toggle action was not necessary on my system.)

Now we'll move on to our second row, which will hold two labels: one indicating that that we are looking at the result of the matching function, and one displaying the result itself (i.e. if there was a match between the user-supplied hash value and the actual hash value of the user-supplied file or not). We'll also need a string variable to hold the desired result message.

The code above is pretty straightforward, and very similar to what we did for the previous row. We have a label indicating that we're dealing with the result, embedded it in row 1, column 0, and made it sticky to the east. Next we set a string variable as an instance attribute because we need to be able to set it from other methods, and provided it with a default text string. Finally, we have a third label that we are going to set dynamically with the appropriate text indicating the outcome of the hash check.

If you run the app now and play around with it a bit, you'll notice you are able to copy the string variable text associated with the 'Hash Value:' label, but that you cannot copy the string variable text associated with the 'Result:' label, just as we desired. Here's the current state of the interface with background highlighting of the three basic frames we've constructed: the banner (blue), the inputs (white), the outputs (green):
With that, we're done with the first stab at our outputs widgets. Wow, that was easy, no? We may find ourselves tinkering with these widgets a bit more as we add the last layer of functionality to the app. We're now ready to configure our app's buttons, and hook them into our inputs and outputs through their corresponding actions! You can review previous articles from this Python tkinter tutorial at the link. You can find the next article in our tkinter tutorial series (part 5) at the link.

PyGest: A Python Tkinter Tutorial, Part 3

This is part three in our Python tkinter tutorial series on building a simple GUI app to compute and check file hash values. In part two, we added a banner header to our bare bones view by inserting a tkinter label into our app's content frame. In this segment, we will build out our app's various input widgets. Recall our mockup design:

We'll continue working our way from top to bottom, and add in those components relating to the application's inputs: 1) the file path, 2) an optional hash value to check against, and 3) a choice of hash functions to run against the file. Altogether, we'll have six objects to configure: two labels, two corresponding input fields, and two radio buttons. We'll also get a glimpse of tkinter's more advanced  functionality by implementing a native window dialogue that lets the user choose the file that will be hashed. This will be the most involved article in the series, so make sure your caught up with the current state of the code, get a cup of coffee and settle in.

Configuring the Inputs Frame
As with the banner, we'll create a new method to configure the input-related objects, and call it from our setup method. However, because there are a number of inputs, we'll group all the objects in this method inside their own frame, defined specifically for the purpose. To make space for this group's frame in the GUI, we'll also have to configure a new row in our main_frame object, and then drop the input objects frame into that row. To begin, let's get the preliminaries out of the way.

We've made a few additions to our View class in the snippet above. We've created a configure_inputs method with a simple log message, and called it from set_up(). In the configure_mainframe() method, we've added a single row to the app's outer frame. (We'll soon attach the inputs frame to this cell in the grid.) In configuring the new row, we identify it as row 1 and give it a weight of 1. Notice, the weights of both row 0 and row 1 are equivalent, which means they will expand and contract in the same proportion when the window is resized. We will change this in due time. Now on to the inputs.

In the configure_inputs method, we are going to configure a new frame using the grid geometry manager, and attach the various input objects to the appropriate cell in this grid. Looking at our mockup, the app's input objects are basically organized in a 3x2 grid: three columns to hold a label, an input field and a radio button in a single row, and two rows to hold each of the sets of these objects. We'll begin by creating our inputs frame and dropping it into the new row we just created in  the class's self.mainframe property. We will add columns and rows to our input frame as necessary.

Here we begin laying out our inputs frame with some basic settings. This frame is pretty much self-contained, so we don't have to make it accessible as a class attribute. We define it as a tkinter.Frame() object and pass in a number of arguments: self.mainframe is the pre-existing object we want to embed it in, and we also give it some styling to make it stand out against our temporary blue background. In the next line of code, we place the inputs frame in the desired grid cell in the self.mainframe object. Our banner is already at row 0, column 0. We'll put the inputs frame just below it, at row 1, column 0. We then make it sticky NSEW to start (we'll tweak this later as we add more elements to the frame). Finally, we configure column 0 and row 0 in the input_frame itself, giving each a weight of 1. By the end of this article, our inputs frame will have three columns and two rows.

Our input frame now has one cell, located at row 0, column 0. In our mockup, the top left object from among our input widgets is the label alerting the user to enter a file path. So let's add that first.

We define the file path label as a tkinter label object, and pass it the appropriate arguments to embed it in the inputs frame with a descriptive text. We also use kwargs to define a background and foreground color to get a sense for how the objects are laid out within the frame. In the next line of code, we then place the label at row 0, column 0, and make it stick to the east side of the cell because we predict it might be nice to have it flush against the entry input field once the other elements are added to the frame. Play around with some different variations of the sticky options to get a sense for how they affect the placement of the label text.

Just to the right of the file path label, we need an input field where the user can enter the path of the file to be hashed. In tkinter, this is called an Entry object. Let's think for a second about how we want to get this input. We can have the user actually type in or copy and paste the full file path as a text string. However, that is obviously not ideal. It would be more convenient for users to be presented with a dialog window that allows them to choose the file from their file system. Or better yet, both! As a first approach, we'll thus configure a text entry field so that when it is clicked it generates a file dialog that allows the user to choose the appropriate file from their local system. Then, when a file is chosen, its full path will be inserted into the entry field.

This will obviously make things a bit more complicated to code than simply just having the user enter a full path text string, but it will make the app much more user-friendly in the end. Plus, it will allow us to demonstrate one of the helpful additions to the tkinter library. Indeed, as we'll soon see, the tkinter library has just what we're looking for!

We thus want to configure a simple Entry object and then bind a click on that field to the generation of a file dialog. It makes sense to put the logic for the file dialog in a separate method. But we'll also have to access the Entry object from that method, which means we should define our Entry object as an attribute of the class. Here's our next snippet:

We want to embed this Entry object next to the file path label, so we have to add a new column to the input frame (see line 16). This is column 1 in the frame, and we'll give it a weight of 1 to start. Then, just below the label, we add the necessary code for the entry object. First, we define self.file_entry as a tkinter Entry object embedded in the inputs frame (line 22). In the next line of code, we call the bind method on the Entry object, and in the arguments, we connect a button-type single click event to our custom file dialog method, which we've called chooseFileName().  (For more info on events and bindings, see the effbot docs.) Finally, we call the grid method on the entry object to identify the cell we want to attach the entry object to in the inputs frame: it's going to be at row 0, column 1. As you can see from the above, the chooseFileName method is just a place holder at present, but it does log a message every time the method is called. If we run the code above, you should see something like this:

When you run the app, if you click inside the box delineating the Entry object, you should see the log message from the chooseFileName method, which is bound to be called on that event.

Weighting the Grid
However, if you run the app and play around with it a bit, you'll notice some strange behavior. For example, when you resize the window, you'll see that the banner header field expands with the window. Indeed, right now the banner will take up exactly half of the vertical space of the window, no matter what size it is. That's because there are only two rows in the main frame (one of which contains the banner header label object), and both of these rows have been configured to have a weight of 1, which means they resize proportionately to one another. Go back up to your configure_mainframe() method and change the configuration of row 0 to have a weight of 1: self.mainframe.rowconfigure(0, weight=0). You'll see the difference immediately: the banner header will no longer expand vertically when you resize the window.

Tkinter File Dialogs
Let's now fill out the chooseFileName() method. What exactly do we want this function to do? When the user clicks the file path entry field, we want a native-looking pop-up to appear that lets the user choose a file from his or her local system. Then, once that file is chosen, we want the window to close and the file path to appear in the file path text entry field. For this, we are going to utilize one of the new additions to Python tkinter: the filedialog submodule. It contains a number of helpful objects and functions, indeed, it has the exact one we are looking for: the askopenfilename() function.

As I understand it, the filedialog submodule has to be imported separately from tkinter itself. At the top of the script, let's thus import the filedialog submodule as fd: import tkinter.filedialog as fd. Our imports now look as follows:
import tkinter
import tkinter.filedialog as fd
import hashlib
import logging
Now, in our chooseFileName() method, we call the fd.askopenfilename() function, pass it a descriptive title, and log its return value (notice we're also passing the bound event itself to the method!):

If you run the app with this code, when you click on the file path entry field, it will generate a native file dialog asking you to choose a file from your local system. The title you supplied will be written to the top of this window. Furthermore, if you use the generated dialog window to choose a file, you'll see that the full path of the file is returned by the function when you pass the returned value to your logger.

Now we want to write that file path to our text entry field. This is accomplished by calling the insert method on the file entry class attribute object. We want to insert the file name beginning at index zero inside the entry field. This is why we needed to have access to the file_entry object outside of its method's local scope. So we add the following:

We're going to need to access the full file path later when we run the hash, so we might as well create a class instance attribute for the file path, and save the returned value from the file dialog to that variable. I also declare this attribute in the init() method just to be explicit about things. In chooseFileName, we call the insert method on the self.file_entry class attribute, and pass it two arguments: the index at which we want to insert the desired string, and the string returned by the file dialog. If you run the app, click the entry field and choose a file, the full path should now be written to the entry field once the file dialog window closes. Things are coming along nicely.

Radio Button and String Var
With our chooseFileName helper method finished, we can now return to work on configure_inputs(). Recall, our app is supposed to allow a choice between running a SHA1 hash or an MD5 hash of a file. SHA1 will be the default because it is more secure, so we'll place it on the top. Let's add the third object in the top row of the frame: a radio button that corresponds to the first option from among the two hash functions our app will utilize. First we have to add a third column to our inputs frame so we have somewhere to put the button! Of course, the third column is actually at column index 2 in our grid. The configuration of our inputs_frame object thus now looks as follows:

We're using radio buttons for the hash options rather than, say, check boxes, because a choice between radio button options is mutually exclusive. (It might be nice to perform multiple hashes at once, but we're trying to keep things simple here.) In our app, the user can choose to hash a file with SHA1 or MD5 by checking the appropriate radio button. We obviously need to keep track of which radio button the user has chosen so we can run the right hash function. To that end, we will utilize a tkinter string variable. We thus define a tkinter string variable, exposing it as a class attribute (since we will need to access the value of this variable to run the hash function), and give it a default value of 'sha1' with the set method, since that is the name of our default hash function. We add two lines to the bottom of our configure_inputs method to define the string variable:

We've also appended two more lines to define our top radio button. The first defines our sha1 variable as a tkinter.Radiobutton() object, and we pass in four arguments: 1) the name of the frame where we want to embed the button, 2) the text that will appear in the GUI next to the button, 3) the corresponding tkinter StringVar we want to associate this radio button with, and 4) the value to send to the string variable if this button is chosen. In the final line, we place the button in row 0, column 2 of the inputs frame identified in the previous line. Our app now looks something like this:

With that, we've reached the halfway point of our set task for the present article! At the top of our inputs frame, we've added 1) a label, 2) a text entry input, bound to a file dialog pop-up window event, and 3) a single radio button. We now have to add the second row. Like the previous row, it will hold: 1) a label indicating where the user can insert a hash value to compare against the hash of the file performed by the app, 2) an entry field where the user can insert that value, and 3) the MD5 radio button. Fortunately, we won't have to hook up the text entry input to a separate function, and now that we have the top row done, the second will be rather easy to implement.

First, we have to configure a second row in the input frame, and then we add two lines each for the label, text entry and radio button widgets:

We've added a digest_label to the inputs frame, with the text "Compare Digest:", and inserted it at row 1, column 0 in the frame, and made it sticky to the east. Secondly, since we are going to need to access the digest_entry field from other methods (in order to get the value we want to compare our hash with), we make it a class instance attribute and define it as an Entry object in the inputs frame. We then place it at row 1, column 1 in the grid and make it sticky to the east and west. Finally, we create our MD5 radio button, define it as belonging to the inputs frame, provide the text we want to appear in the app, define the variable it is attached to (i.e. the StringVar object variable we set up earlier, to which we've already attached our SHA1 button), and give it a value of 'md5' so we know when it has been selected. We then place it in row 1, column 2 of the grid. Our app is coming along nicely:

That took a bit of work, but now we're done configuring our app's inputs! Here is the current state of our code:

In the next article, we'll implement the various objects necessary to display our app's output. Thanks for following along! You can find part 4 in our Python tkinter tutorial series at the link.

PyGest: A Python Tkinter Tutorial, Part 2

This is part two in our Python tkinter tutorial series. In part one, we defined the basic structure of our script, set up a logger, and got the root window of our GUI application up and running in the app's single view class. In the present article, we'll begin work on the main view in earnest. We will configure the tkinter root object, create and configure a single frame to hold all the app's contents, and then create our app's title banner. First, however, we should discuss how to structure the layout of a Python tkinter application, and our strategy for doing so in the present project.

From what I've read, it appears that a lot of people had been turned off by Tkinter in the past because of its' seemingly weird geometry management, which involved a choice between placing widgets, or packing them or putting them in a grid, when building a layout. The docs suggest using the pack method over the placement method. It is thus no surprise that many tutorials and reference web sites utilize the pack method.

But the pack method never really clicked for me when I first started playing around with Tkinter in Python 2.7 a couple years ago. These days, in Python 3.4, the preference is to configure tkinter views using the grid geometry manager. This method is suggested by Russel Keith-Magee in his defense of tkinter (mentioned in the introduction to our series), and I've come across other recent discussions of the module making a similar argument.

Grid Geometry Management: Grids of Grids
In terms of its geometry, our app will consist of a grid of grids. First, we are going to configure the root window as a 1x1 grid. Into that single root cell, we'll then install a main outer frame, which we'll structure as a grid that will grow as we add more components to our interface. We will then group related individual widgets (labels, inputs, buttons, etc.) into their own frames in a grid format, and then drop these frames into the desired cell(s) of the main outer frame's grid as needed to build our interface.

For the purposes of this tutorial, we are going to structure the View() class by creating a setup method that is run on initialization of the class. This method will call a series of others methods that build the individual elements of the app: root window, main frame, banner, input fields, output fields, button box, etc. We will build out these various methods in subsequent articles until we have a working model of our mockup design.

Configure the Root Window
Beginning from where we left off in part one, we'll now add our set_up() method to the View class, and call it from init(). In set_up(), we'll call another method, configure_root(), where – you guessed it – we configure the root window. We're going to set some basic properties on the root window by calling two methods on the self.root attribute in the View class: columnconfigure() and rowconfigure(). It is here that we could also call methods such as minsize(), if we so desired.

We use the columnconfigure() and rowconfigure() methods on root to define the properties of the outermost grid in our app. These methods each take an integer parameter defining which column and row we are referring to (in our case, since we are building a 1x1 grid, we'll be defining column 0 and row 0), as well as a kwarg that defines their respective weights to be 1. The weight keyword argument determines how the cell responds when the window is resized. Giving them both a weight of 1 means they will resize proportionally to each other when the window is resized. Your View class should now look as follows:

Learn to love the column and row configuration methods! They are the primary means by which we'll define where our app's widgets live, and how the individual cells of our app respond to changes in the window size. There are other configuration options for the root window which you can play around with on your own, but we're now done configuring the root window for the purposes of PyGest.

Configure the Main Frame
We'll now configure the main content frame of the app. As mentioned above, we are going to drop this content frame into the single cell we just defined for the root window. Unlike the root grid, this content frame will be variable in size and will grow as we add more widgets to the interface. Define a new method called configure_mainframe() in the view class and call it from the class's set_up() method. For now, we are going to add five lines of code to this method. Later we'll see it grow along with the rest of the app.

If you run the app now, you may find that your window has mysteriously disappeared! No need to panic, we'll get to that in a second. (Hint: call the minsize() method on the root object.) There's a lot going on in our configure_mainframe() method. Always start with a comment. After that, I added a simple log to make sure the method is actually being called  – since I initially forgot to call this method from set_up!

Next we define the app's main frame as a tkinter.Frame() object. Notice I'm defining it as self.mainframe, i.e. as an instance attribute of the class. This is because we are going to have to reference this attribute from other methods as we add more widgets to our app. (Though not strictly necessary, I also declare this attribute in the init() method of the class and assign it an initial value of None just to be explicit about its existence, and to make my IDE stop complaining about the fact that I've defined an instance attribute outside of init().)

We thus define self.mainframe as a tkinter.Frame() object and pass it two arguments. The first identifies the pre-existing object into which we want to embed this frame. We only have one such object right now (the root window of the app!) so we pass in self.root. I've also given the frame a background color to provide visual confirmation that it is in place. You can explore other parameters in effbot's reference documentation.

Next, we call the grid() method on our newly declared mainframe object, and pass it three kwargs. The column and row arguments determine where the self.mainframe object will be located within the self.root grid that we are attaching it to (as defined in the previous line of code). Our root grid only has a single cell, with the coordinates row 0 and column 0. So that's what we pass to the mainframe's grid method. Finally, we pass in the kwarg sticky, which we define as north, south, east and west. This means that the mainframe object will stick to the north, south, east and west sides of the cell to which it has been attached, if the size of that cell changes.

Finally, we configure a single column and a single row for our mainframe content grid, and give them each a weight of 1, just as we did for the root window. At present, our main frame is now a 1x1 grid, embedded in the single cell of the root window's 1x1 grid. As we add widgets to our interface, we will add more columns and rows to the mainframe grid as necessary.

As mentioned above, if you run the app with the code above, you may find that your window as mysteriously disappeared! This is because it has nothing in it except for an empty frame! By default, tkinter windows and cells always shrink down to fit the size of their largest element. Since our frame is empty, the window is minimized to the maximum. You can easily resize the window by calling the minsize() method on the root object in your configure_root() method: self.root.minsize(200,200).

Running the app with the code above, not much should change except for the fact that the window is now blue (or whatever color you've decided upon). If you resize the app, the main frame will stick to all four sides of the root window, and the window will remain blue. However, if you play around with the sticky kwarg by using different combinations of north, south, east and west, you'll see some perhaps surprising changes in the look of things.

For example, if you make the frame sticky only to the north and south, you'll see a single vertical line through the middle of the window. If you make it sticky only to the east and west, you'll see a single horizontal line through the middle of the window. This is because in tkinter, by default, a widget object is only as big as its biggest element. But our main frame doesn't have anything in it yet, so it collapses down in this seemingly weird way.

Configure the Banner
We now have a single root window structured as a 1x1 grid. We've embedded a single frame in that root window, and this frame is (for the time being) also structured as a 1x1 grid. As we add components to our interface we will add more rows and/or columns to this frame as necessary. Let's start to fill it out by giving it a header banner that displays the name of the app. First things first, define a new method inside the View() class called configure_banner(), call this method from set_up(), give it a basic comment and a log message.

We are going to display our app's name in the title banner using a simple label object. However, we now have a choice. Label is one of the objects that can be found in both tkinter and the ttk submodule. (As mentioned in part one, the ttk submodule contains widgets that are not available in the top level tkinter library, ex. Combobox, and also "gives the application an improved look and feel," according to the docs.) Objects that are in both the tkinter top level library and the ttk submodule are styled in a slightly different manner. Styling parameters are passed directly to top level tkinter objects like labels, whereas for ttk objects you have to configure these objects using the style class. You can play around with both to get a sense of the differences, if you like. For the sake of simplicity and backward compatibility, we're going to use a basic tkinter label here.

The configure_banner() method in our View() class is going to be very simple. It will have two critical lines of code: the first defines the banner as a label attached to our main frame and gives it some basic styling, and the second defines where the label will be placed in the main frame's grid as well as some other parameters. Here's the code for the configure_banner() method:

Under the comment and the log message, I define the banner variable itself as a tkinter label. We're passing five arguments to the tkinter.Label() object: 1) self.mainframe is the object we are attaching this label to, 2) we're making the background black so we can see it, 3) the text kwarg defines the text that will be displayed in the label, 4) the font kwarg is assigned a tuple that contains the name of the font and its size, and finally 5) fg (which stands for foreground) defines what color the foreground text is (note, you can also shorten the background kwarg to bg).

In the final line of the method, we specify the behavior of the object itself by calling the grid method on it. We're passing in five arguments here as well. The row and column kwargs specify where the banner will appear in the mainframe object in which it is embedded. We want our banner to appear at the top of the interface, so we're putting it at row 0, column 0. (We'll drop our next object into the app just below the banner at row 1, column 0 in the main frame.) Next we make the object sticky to the north, south, east and west to start. Finally we give it some horizontal and vertical padding to give the object a bit of breathing room.

If you had previously defined a minimum size for your root window with the minsize() method, you should comment that out, so you can see how the default window sizing works now that we have an object with some substance embedded in the frame. Here's the state of the app with its banner and debug coloring:
With that done, we'll end the present article here. We covered a lot of ground in this post, and  introduced the basic development flow that we'll follow throughout the remainder of the series. Play around with the various parameters for the main frame and the banner, and start exploring other tkinter widgets. In the next article, we will configure the necessary widgets for our app's inputs: labels, text entry objects, and radio buttons. Here's the state of our code:

Thanks for following along. As always, questions, comments, critiques and suggestions are welcome in the comments. In the next article in the series, we will build out the widgets relating to our app's user inputs: labels, text entry fields and buttons.You can find the next article in the series here.

PyGest: A Python Tkinter Tutorial, Part 1

This is part one in our tutorial series on building a simple Python GUI app with tkinter. You can find the introductory article to the series at the link. In this article, we'll get things up and running by filling out the basic structure for our Python script and the application itself. We'll add a top level comment, define the necessary imports, set up our main name space, define the main function, and then configure a logger to aid in sanity checking . . .

Our app doesn't have a name yet. Typically, Python application names have a 'py' prefix or suffix attached to a word describing the app itself. Since this app processes hash digests, we'll call it PyGest, for lack of a better idea. So we'll create, add our top level comment and our main namespace. Then we define our main function with a comment and a pass for the moment, and then call this function from the top level script environment.

Let's talk about imports. We don't need to import that many libraries for our little app. We'll use the hashlib module to perform the hashing operations, the logging module to help with debugging, and, of course, the tkinter library. The imports for tkinter require a bit of explanation.

With tkinter it is common practice not to import the module itself, but rather all the elements in it directly (i.e. "from tkinter import *" instead of "import tkinter"), which is normally frowned upon in other contexts. Perhaps this is to avoid unnecessary keystrokes? However, in this project, we're going to flout convention and import the module just like any other, i.e. "import tkinter". This will require us to explicitly declare the module's name when we call up one of its objects (ex. tkinter.Label()), but it will help us keep better visual track of tkinter objects in our code.

Secondly, one of the additions to the tkinter module in Python 3 is the ttk submodule, which offers many of the same objects as the tkinter module itself: labels, buttons etc. However, it also contains a number of widgets that are not in the tkinter standard library (ex. combo boxes), and its objects are optimized to take on the native look of the OS platform running the app. (Personally, on my system, I can't tell much of a difference between the look of most tkinter widgets and ttk widgets.)

For our tutorial app, we're not going to be doing anything especially fancy, so I've opted not to use the ttk submodule, as all of the widgets we'll be using that are in ttk can also be found in tkinter proper. Moreover, widgets in the ttk submodule require a different styling format than the same widgets in tkinter, so keeping to the main library will make much of the code that follows accessible to folks working in Python 2.7. For more on the ttk submodule, see TkDocs. (Note that in Python 2.7, the tkinter module has a slightly different name. It is capitalized: Tkinter. And the ttk submodule is not available, as far as I'm aware.) With that, let's add our imports.

To aid in sanity checking, I like to configure a basic logger at the beginning of a project. If you're not familiar with the logging module, read up on it a bit in the docs. The idea is simple: we configure a logging object and then call it when we want to report info from the program while it's running. Of course, you might also consider just using print statements, but a logger can provide more information such as the time, the line number in the script, indicate levels of severity, in addition to providing a particular message. I'm also going to declare a 'title' variable with the name of the application.

So I define the title variable just underneath the import statements, then configure the logger inside the main function, and log a message indicating that the app has started up. This logger configuration logs the time, the line number, the level name and a message. For all the basic logging configuration options, see the docs.

Alright, let's get down to business. Tkinter works by running a tkinter.Tk() object in an event loop that can react to defined user inputs such as button clicks, mouse events, keyboard inputs and the like. In our application's main function, we will: 1) initialize our Tk() object as 'root', 2) configure the application's title by passing it to the root object, and then 3) pass the root object to our application's main view.

The main view will be a Python class that we use to configure, structure and build our interface. We thus add four lines to our main function. Notice that when I pass the root object to the view, I'm assigning the return to a variable. I have seen inconsistent explanation of this idiom, but it appears to be standard practice.

Of course, running the script above will result in an error since we haven't defined our View() class yet. So let's do that now. The View class will accept one argument, the root object. In the init() method, we'll define the root argument parameter, then assign the root object to a class instance variable appropriately named 'root'.

If you run the script above, you'll see your log message written to the terminal and then the program will appear to hang. But if everything's working properly, that's just what we would expect because it has launched the tkinter root window, which should be running its main loop. If you don't see the application's window, cycle through the applications that are open on your desktop to find it. By default, the tkinter root window does not take focus, and may be hidden behind them (it's nice like that). In your system's list of running applications, you should also see an icon indicating that the Python app is up and active. Here's what the empty root window looks like on my system, with a default size of about 200x220px:
If you can't seem to find the window even though the app is clearly running, it may be that the window is being drawn, but is not big enough to be seen. In that case, try setting a minimum size to the root window. Just after you pass in the title to the root object, add a line such as the following: root.minsize(300, 300).

To exit, you can just close out the window. Notice, if you press <Control-c> on the keyboard when in the terminal, the program does not stop running until focus is returned to the root window itself. With that, we've got the seed for our application in place.

In the next article, we'll begin the process of building it out, widget by widget. You can find the second article in the series at the link.

PyGest: A Python tkinter Tutorial, Introduction

In this tutorial series, we are going to build a simple file hashing application using the Python standard library's interface to the TK GUI toolkit: tkinter. One can find some resistance to using tkinter in the Python community. However, my interest in tkinter was recently rekindled after watching "Tinkering with Tkinter", a presentation by Russel Keith-Magee, in which the Django developer makes a strong case for revisiting this often overlooked and under-appreciated component of the Python standard library . . .

As Keith-Magee points out, these days tkinter has a number of arguments in its favor: 1) it is in the standard library, 2) it has been greatly improved in recent years, with additions to its basic functionality (more widgets!) as well as improvements in the look and feel of the GUIs it can generate, and 3) new resources such as the website TkDocs provide a ton of information to get Python tkinter GUI apps up and running in a relatively short period of time. Keith-Magee walks the walk as well, having built Cricket – a GUI tool for running Django and Python test suites – entirely with tkinter.

Our goal here is much more modest. We're going to build a single view file hashing utility in a manner appropriate for people with some experience programming in Python, but little or even no experience in Python GUI programming. Why would anyone want to build a file hashing utility? Simply put, hash functions can help determine the integrity of a file. For example, if a developer provides the hash value of a given file along with a download, you can check the hash value of the file you've downloaded against the one supplied by the developer to test whether the file was corrupted or modified in transit. (If you're new to the concept of hash functions or need a refresher, check out our past article on How and Why to Check a File's Hash Value.)

With that determination, we can already specify the basic functionality that we'd like our tutorial application to have. It should be able to: 1) generate hash digests of a specified file, 2) check the result against a known hash value, 3) alert the user as to whether or not there is a match, and 4) provide a choice of hash functions to use in the process.

Our application will thus need: 1) a number of labels to orient the user, 2) input fields for the file's path and the hash value to check against, 3) mutually exclusive radio buttons to choose the hash value, and 4) some buttons to run the program and clear the contents of the input fields. The project will thus provide us with the opportunity to play around with the basic elements of any GUI application. Here's a simple mockup:

We are going to use Python 3.4 throughout, but much of the code that follows should also work in Python 2.7, and I'll try to provide pointers as to when and why it might not. In case anyone is interested, I'm building this using the PyCharm Free Community Edition IDE on a Macbook laptop. Please note, there may be, or rather, it is virtually certain that there are far better ways to code the application presented in this tutorial. I built the GUI on the basis of my own idiosyncratic research into the tkinter library, and have organized the project to make it easier to present and digest in this tutorial series.

In the next article, we'll begin by laying out the bare bones structure of the application. Then we'll use a grid layout manager to construct our primary view as a set of grids within grids. This post will be updated with links to each successive article in the series as it is uploaded to the site. Enjoy! As always, any and all suggestions, comments and critiques are welcome in the comments. You can follow along with the tutorial using the links below:

PyGest: A Python tkinter Tutorial, Part 1 
PyGest: A Python tkinter Tutotial, Part 2
PyGest: A Python tkinter Tutorial, Part 3 
PyGest: A Python tkinter Tutorial, Part 4 
PyGest: A Python tkinter Tutorial, Part 5 
PyGest: A Python tkinter Tutorial, Conclusion
Comments (3)

Swift Networking Tutorial Index: Building a Swift App to Query a Custom API

Our tutorial series on networking in Swift provides a detailed, practical overview of the topic from the back-end API to the end user application. The series is broken up into two major parts. In the first part, we build a custom web service in PHP which provides access to a RESTful API that serves inventory content from a hypothetical plumbing supply shop. Knowing how to create a simple API is useful for delivering mock content during your app development cycle, and provides application developers with more knowledge on precisely how such a service is constructed. In the second part, we use table views to create a Swift application to query our custom API and deliver the contents of the service to the end user of the application. Use the index below to navigate the tutorial.

Introduction and Overview: From the Back End API to the End User Application

The Web API
Building a RESTful API in PHP, Part 1
Building a RESTful API in PHP, Part 2

The Swift Client App
Networking in Swift: Building the Swift Client, Part 1
Networking in Swift: Building the Swift Client, Part 2
Networking in Swift: Building the Swift Client, Part 3
Networking in Swift: Building the Swift Client, Part 4
Networking in Swift: Building the Swift Client, Part 5

This tutorial was authored by Stefan Agapie, a Senior iOS Software Engineer, and adapted for the present piece.
Comments (4)

Networking in Swift: Building the Swift Client, Part 3

This is part three in the tutorial segment on building a Swift client application to query a RESTful web API, from our series of articles on networking in Swift. In the first segment, we created a custom RESTful API in PHP that serves up the inventory of our hypothetical plumbing supply shop.

In this segment, we have been building a Swift client which queries this API and delivers that inventory content to our end user. In part one, we got our Swift application up and running. In part two of building the Swift client, we created our basic data model, hooked up the segues to our inventory views, and successfully handled raw responses from the server by printing them to the Xcode console.

In the present article, we'll create model objects from the JSON dictionary returned by the server (at the end of part two), and display our inventory item lists in their respective table view controllers.

Model Objects
When we left off in part two, we were filling out the requestInventory method in our PlumbingSupplyInventoryTableViewController. Currently, that method simply prints the returned JSON dictionary to the Xcode console. We'll now create model objects from this dictionary by factoring out the relevant code from the requestInventory method and placing them in a separate method to handle this logic. In your PlumbingSupplyInventoryTableViewController file, add the following method below the requestInventory function that we were working on in the previous article:

Notice that in the last line we do not print out the jsonResult dictionary object but instead wrap it in an array and return it to the caller. In the requestInventory method, replace the three lines of code we factored out into the new inventoryItems method with the following two lines of code:

If you run the app and select one of the two inventory item categories, you should see the same response as before in your console, but wrapped in an array. We'll now refine the raw JSON data. Replace the return [jsonResult] line of code in the inventoryItems method with the following snippet:

Let's take a closer look at this. The first line gets the raw data dictionary object from the JSON results container. The second line defines a container that will hold model objects that are built from the raw data dictionary objects from line one. Inside the for loop we iterate through the raw data dictionary objects and build an array of refined data objects. And in our last line we simply return the array of model objects.

If you now run the app again, you'll see the difference in the Xcode console output, which now returns a tidy array mapping individual inventory items to their memory locations. Let's display these inventory lists in their respective views.

Displaying Our Inventory Item List
Return to the main storyboard. Locate and select one of the table view cells from our PlumbingSupplyInventoryTableViewController scene. In the Attributes Inspector, locate the Style drop down menu and select the option “Basic.” Locate the Identifier field and type in “Cell”. Finally, locate the Accessory drop down menu and select the option “Disclosure Indicator.” Do the same for the other cell as well.

Now open the file PlumbingSupplyInventoryTableViewController.swift file. Inside and toward the top of the class, add the following property:

This data source property will supply our dynamic table view cells with the information to display on screen. The number of items in our data source will always be equal to the number of items from a single plumbing supply inventory category. In the same class  replace the default boilerplate code for the three methods below with the following snippets:

These data source methods are called by the system to query this controller on how to proceed when building our table view and displaying content within it. In the first method we simply tell the system that our table view will display only one section. The second method says that the number of items in our single table view section is equal to the number of items in our data source.

The last method does several things to build a table view cell. In the first line (line 12 in the snippet above) it dequeues a reusable cell. When scrolling a table view, table view cells that scroll off the screen are placed on a queue for reuse and cells that scroll onto the screen are removed from this queue and reused. This process helps speed up table view performance which makes possible the smooth table view scrolling with which we are all familiar. On the second line (line 13) we utilize the indexPath object to get the row number of the cell that is next to become visible in our table view; the row number corresponds to a unique item in our data source. There is a one-to-one correspondence between the cells and the items in our data source. The following line gets the name of an inventory item and assigns it to the label of the next cell to become visible. The last line simply returns that cell.

Let's jump back to where we defined our requestInventory function. In this method, replace this line of code that reads println(inventoryItems) with the following snippet:

What's going on here? In line 1, we capture a reference to the data source that is received from the self.inventoryItems(data) method call. The next segment is a C level API call to a dispatch system, on a queue of our choice, which executes code that we place inside its block/closure. The code inside the closure performs updates to our UI elements.

According to Apple's documentation, any code that updates UI elements must be executed on the main queue—which is what we do. The first line within the closure asks our table view to reload since we have assigned items to its data source. The second line hides the web activity indicator spinner, since our request for web content has terminated. Run the app and select on of the two plumbing supply categories. Once the content downloads you should see a table view similar to the one depicted below:

Success! We've successfully displayed the list of inventory items returned by the web API. Notice, however, that we did not use the callback responseHandler( error: nil, items: nil) closure but instead updated our UI in the method from above. We leave this as an exercise for the reader to implement. If you are not sure how to go about implementing this, don't worry, we wrote another method on a different controller that uses the closure to update its UI elements after an update. We do this towards the end of this tutorial.

This project can be found on GitHub.

We're almost done! In the next article, we'll display thumbnail images alongside each of the items in our inventory list above. And then in the final tutorial, we'll build our item description scene for each item in the inventory that displays the full image along with the extended description supplied by our API.

Introduction and Overview: From the Back End API to the End User Application

The Web API
Building a RESTful API in PHP, Part 1
Building a RESTful API in PHP, Part 2

The Swift Client App
Networking in Swift: Building the Swift Client, Part 1
Networking in Swift: Building the Swift Client, Part 2
Networking in Swift: Building the Swift Client, Part 3
Networking in Swift: Building the Swift Client, Part 4
Networking in Swift: Building the Swift Client, Part 5

This tutorial was authored by Stefan Agapie, a Senior iOS Software Engineer, and adapted for the present piece. 
Comments (2)

Networking in Swift: Building the Swift Client, Part 2

In the first part of this tutorial segment on networking in Swift, we got our client app up and running with a simple table view controller listing the two inventories supplied by the RESTful API we created in the initial segment of the series. In the present article, we will: 1) set up our data model, 2) create the segues to our inventory views, and 3) process raw responses from the server asynchronously. 

Building the Item Data Model
Our code looks better and becomes easier to manage when we build objects that represent or model the data items that we receive from our web service. To this end, we'll create a file for our individual plumbing supply items using a Cocoa Touch Class template, and then fill it out with the necessary parameters supplied by the API. Open up your Xcode project if you haven't already. In the Xcode Project Navigator panel, right click on the top most group folder. From the menu options that appear, select new file.

You will be presented with a set of options similar to this:

Under iOS, select Source, followed by Cocoa Touch Class, then click Next. Under the secondary menu options: next to the 'Class' field type in PlumbingSupplyItem. For the next field, 'Subclass of', type NSObject, do not create a XIB file (uncheck box), and for the Language portion ensure that Swift is selected:

Click 'Next'. When prompted to select a destination, place the file alongside the other project files. If the file is not automatically loaded into Xcode, then open it from the Project Navigator panel. Now place the following code within the PlumbingSupplyItem class implementation:

As you can see, this code block models the data item passed from the RESTful API we built in the previous segment of this tutorial series, initializing an item id, an item name, an associated image and an item description. It doesn't get much simpler than this.

Segues to the Inventory
With our data model in place, we'll now create our controller class for our inventory, using a table view. This will allow us to mediate between the two inventory table views upon a touch event by the end user.

In the same manner that we created the PlumbingSupplyItem model file, create a new file named PlumbingSupplyInventoryTableViewController using a Cocoa Touch template, and have this file subclass a UITableViewController. From the Object Library, located in the Utilities panel, drag and drop two UITableViewControllers into the main storyboard as depicted below:

Select one of the two view controllers that were just dropped in. Now, in the Identity Inspector, located in the Utilities panel, find the Class field, and type in the name of the class we just created (i.e. PlumbingSupplyInventoryTableViewController) as shown below:

Do the same for the other controller as well, since we are building two separate views of the same kind of object, i.e. items in each of our two inventories.

Note that when you are zoomed out in a storyboard, you can only make selections on the view controllers themselves. To make selections on a controller's internal elements, you have to zoom in. Armed with that information, go ahead and select the cell with the label 'Plumbing Tools'. While holding down the Control key and the left mouse button, drag your mouse over to the top right most view controller and release. During this motion you should see a blue line stretch from our starting location, the table view cell, to our final destination, the view controller.

Upon releasing your mouse button over the controller, a menu will appear. Select the top option that reads: Selection Segue->Show.

Now repeat the same steps for the other cell as well. Your storyboard should look like the following:

What did we just accomplished? We have set up view controller view transition objects known as segues. These segues will respond to a user's touch of a cell. When a cell is pressed, the associated segue will transition to the view controller that it points to.

Preparing Our Segue
Since we will be using a single view controller to display the different inventories of plumbing supplies from the two possible options, namely, Plumbing Tools and Copper Pipes and Fittings, we need to inform the destination view controller which cell was selected. The tip of a segue arrow is said to point to the destination view controller and the tail of the arrow is said to originate from the source view controller. Create a file named PlumbingSupplyCategoriesTableViewController and have this file subclass a UITableViewController.

Now we'll hook it up on the story board. Select the source view controller, i.e. the controller with the two cells. In the Identity Inspector, located in the Utilities panel, where the field reads 'Class', type in the name of the file and class we just created: PlumbingSupplyCategoriesTableViewController. In the main storyboard, select the segue arrow that is associated with the cell labeled 'Plumbing Tools'. From the Attributes Inspector, located under the Utilities panel, locate the Identifier field and type in: plumbingTools.

Do the same for the other segue arrow, but this time provide the Identifier with the name from the title of the other inventory list: copperPipesAndFittings.

We're now going to jump back to our code files. In the PlumbingSupplyInventoryTableViewController.swift file, place the following code (in line 3 below) immediately after the class definition, like so:

Now, over in the PlumbingSupplyCategoriesTableViewController.swift file, replace all the code inside the class PlumbingSupplyCategoriesTableViewController: UITableViewController { . . . } with the following snippet:

This is a system call method that is responsible for notifying the source view controller that a segue is about to be performed. The title that we set in the code above is to the destination table view controller that we segue to. On this destination controller we also set the plumbing inventory url endpoint so that the controller can load the content that was chosen by its corresponding table view cell. Our destination has enough information to load the entire inventory of the selected plumbing category.

Holding Pattern: Activity Indicator
Before we request a list of inventory items, it is customary to run an activity indicator to show the user that our app is in the process of getting some information to display. In the PlumbingSupplyInventoryTableViewController.swift file, below the line of code that reads var inventoryUrlEndpoint : String = "", enter the following line of code:

This line of code creates an instance of UIActivityIndicatorView and makes it private. Now we're going to fill it out inside the viewDidLoad method. In the same file, but inside the method override func viewDidLoad(), add the following lines:

Save all your files and run the application. Once it loads, segue to the two inventory table view controllers. You should see an activity indicator animation as shown here:

Requesting an Inventory
Inside the PlumbingSupplyInventoryTableViewController.swift file, immediately below the webActivityIndicator property, we'll now define another variable that holds a reference to a URL session object that will asynchronously handle our web request. Enter the following line there:
var urlSession = NSURLSession.sharedSession()
At the bottom of the same class, we now define a function that will perform the url session request, parse the request and send us back objects if the success was successful. Here's our first stab:

If you are new to Swift, this function might look rather cryptic. That's because it is! It was no easy task to get this right—a whole lot of Google engineering was required on our end. Lets break it down by parameter:

    'endPointURL : String'
        - 'endPointURL' is an arbitrarily chosen parameter name that we defined in order to identify this parameter, and the 'String' portion requires that the passed in object be of string type.

        - 'responseHandler' is an arbitrarily chosen name for our closure, a.k.a block in Objective-C.

    'error : NSError?, items : Array<PlumbingSuppleyItem>?) → ()'
        - This portion defines a closure.
        - The 'error : NSError?' segment is again an arbitrarily chosen parameter name, and the 'NSError' portion requires that the passed in item be of NSError type.
        - The question mark (?) indicates that the passed in object is optional, meaning that a nil may be provided—in its absence we are required to pass in a none nil value NSError object.
        - 'items : Array<PlumbingSupplyItems>' indicates that the passed in object is a container that holds objects of PlumbingSupplyItem type. 
        - The arrow followed by the parenthesis '→ ()' indicates that this closure returns no values. Instead, objects are passed through the closure's callback parameters.
        - The second arrow followed by parenthesis '→ ()' indicates that the function returns no values.
        - The arrow along with the parenthesis may be omitted for both the function and closure.

Okay, that was a mouthful, but what happens when the view appears on the screen? Let's define it. Right below the viewDidLoad method, we add the following code for our new viewDidAppear method:

This function will be called by the system when the view appears onto the screen. This is good spot to begin requesting inventory items. Notice that we are calling our previously defined requestInventory function. Let's revisit that function now. Replace all the existing code inside the requestInventory method implementation, with the following snippet:

Let's go through this line by line. Line 1 creates an NSURL object from the provided endPointURL string that is referenced by a constant named url; it is essentially a wrapper object for a string formatted URL. This NSURL object is required by our urlSession object that is on the next line of code.

On this line of code, i.e. line 2, we create what is known as a 'data task' for querying our web service. This call spawns an asynchronous operation that communicates with our PHP web service without blocking the main thread. Not blocking the main thread is highly desired if we want our user interface to continue to be responsive—this makes for a better end user experience. Once the communication with our web service completes, the completionHandler closure and all of our code that is contained within this closure is executed. The closure has three parameters: 1) the raw data that comes from our web service, 2) a response object containing the headers from our web service response, or 3) an error object if the request failed.

Line 4 prints the response object inside the Xcode console.

Line 6 is a call to a closure that we defined for our requestInventory function. The parameters provided are an error object if any, and a list of data objects for our inventory items. Currently, we only return nil values. 

Run the application the select both Plumbing Tools and Copper Pipes and Fittings table view cells. You should see the response objects printed for both selections in your Xcode console. The responses in your Xcode console should look similar to this:

Success! Notice that the response object is of type NSHTTPURLResponse. This response object contains information about the requesting url, and the header fields from our web services. Notice the status code of 200; this means that request was completed without issue. You can also print the data object but in its raw form it will not make much sense—try it if you'd like. The communiqué between the host and client is comprised of two parts. The first part is known as the head or header and the second part is known as the body. A typical request or response will contain both of these parts (It's possible to just request the head of a web service response—Google to find out how). The real-world analogy that is often used to describe this is paper mail. The electricity bill, for example, is comprised of two parts as well. The first part is the envelope itself that contains information about its sender—the head. The second part is the contents of the envelope that contains information for the recipient—the body.

JSON Parsing
Now let's get our raw inventory. To do this, we take the response or body of the message and translate it into a container that we can readily read from. In the same function that we've been working on, replace the following line of code that prints out the response, (i.e. println(response), line 4 in the snippet above) with the following:

The first line of code creates a parse error pointer to an object of type NSError, or nil value. On line 2, we call the NSJSONSerialization class method JSONObjectWithData(. . .) and pass to it our raw data response from our web service along with the memory address of the pointer that we created on the first line.

This last method will convert our raw data into a mutable container of type NSDictionary. If the conversion process fails, then this method will assign an error object to the provided memory address with a description or nature of the failure.

The last line of code simply prints our newly created container to the console screen. Save the file then build and run the application. Navigate to one of the inventory endpoints from the table view. In the Xcode console, you should see a similar response to this:

This project can be found on GitHub.

Success! Our application is now querying our tools and supplies API, and returning the inventory response for each of the categories listed on our primary view controller. In the next article in the series, we'll create model objects and then display our inventory item list in our Swift client. Continue to part three on building the Swift client.

Introduction and Overview: From the Back End API to the End User Application

The Web API
Building a RESTful API in PHP, Part 1
Building a RESTful API in PHP, Part 2

The Swift Client App
Networking in Swift: Building the Swift Client, Part 1
Networking in Swift: Building the Swift Client, Part 2
Networking in Swift: Building the Swift Client, Part 3
Networking in Swift: Building the Swift Client, Part 4
Networking in Swift: Building the Swift Client, Part 5

This tutorial was authored by Stefan Agapie, a Senior iOS Software Engineer, and adapted for the present piece. 
Comments (2)

Networking in Swift: Building the Swift Client, Part 1

If you've been following along from the beginning of this tutorial series on networking in Swift, you're now running a local web server and have created a simple RESTful API in PHP that serves up the inventory for our hypothetical Super PHPlumbing Bros. project. In this segment of the series, we'll build the iOS Swift client to bring that content to our end user. In the present article, we'll start our Swift project from scratch and create a single view application using a table view controller that will serve as the primary interface to our inventory of plumbing tools and supplies.

In the Beginning . . . 
Download and install the latest version of Xcode, if you haven't already, and fire it up. From the Xcode menu bar (or the Welcome screen) select File->New->Project. A window will appear with various options to choose from. In the left hand panel, under iOS, choose 'Application'. And in the main panel select 'Single View Application'. Then go ahead and click 'Next' as shown below.

On the following window you will be asked to name your application. Name it what ever you like. Under the Language section select Swift from the drop down menu. Make sure that the build is for iPhone in the 'Devices' menu, and then click 'Next' again.

You'll then be prompted to choose a location to house your project and will be given the option to place the project under source control. If you know how to use git for source control, then by all means use it! Otherwise, uncheck the box if it is already checked and click 'Create' to start up the project.

Displaying the Available Services
In our Swift application, we want to present the user with all the available services that our supply shop has to offer. Our custom API provides an interface to our inventory of Plumbing Tools as well as our inventory of Copper Pipes and Fittings. To present these options to the end user we are going to use a table view. So let's jump in. In the navigator panel (the left panel) of Xcode, locate and select the file named Main.storyboard.

Once the main storyboard loads, scroll to the pre-loaded Single View Controller and select it. When properly selected its border will turn blue, as seen here:

As we are going to use a table view, we can safely discard this default view controller. Delete the single View Controller by pressing the delete key on your keyboard, while the controller is selected. In the Utilities Panel on the right side of the Xcode interface, locate the Object Library submenu. Select a Table View Controller, and drag and drop it inside the main storyboard. 

While the new controller is selected, point your mouse toward Xcode's menu bar and select: Editor->Embed In->Navigation Controller. This embeds our selected Table View Controller into, you guessed it, a Navigation Controller.

A Navigation Controller is a stack for managing the presentation order of our view controllers. Select the Table View situated inside the Table View Controller, and then select the Attributes Inspector from the Utilities Panel. Locate the 'Content' field and select 'Static Cells' from its drop down menu.

You should see three cells appear inside the Table View. We only need two such cells, as this is where the user will be presented with the option to browse either the Plumbing Tools inventory or the Copper Pipes and Fittings inventory. Delete the bottom cell by first selecting it, and then pressing the delete key on your keyboard. Now let's name our two primary interfaces. For each of the two remaining cells, select the cell, and then locate the 'Style' field in the Attributes Inspector panel. From the 'Style' drop down menu select 'Basic'.

Both table view cells should now display a label that reads 'Title'. Two clicks in rapid succession on a label will place it into edit mode. Modify the titles so that they read from top to bottom, 'Plumbing Tools' and 'Copper Pipes and Fittings', respectively.

In order for the application to run, we need to specify the initial view controller that we want to load when the application first boots up. In the main storyboard, select the Navigation Controller. Then, in the Attributes Inspector menu, locate the check box that reads, 'Is Initial View Controller' and select it as shown below:

In the top left corner of Xcode make sure that the active scheme is set, and click the play button to build and run the application. Once the iOS simulator starts up, your app should look like this:

This project can be found on GitHub.

Success! We've built the primary view that will be presented to the end user when they open our iOS application. In part two of this segment, we'll begin building our data models. You can find part two in the tutorial on building the Swift client at the link.

Introduction and Overview: From the Back End API to the End User Application

The Web API
Building a RESTful API in PHP, Part 1
Building a RESTful API in PHP, Part 2

The Swift Client App
Networking in Swift: Building the Swift Client, Part 1
Networking in Swift: Building the Swift Client, Part 2
Networking in Swift: Building the Swift Client, Part 3
Networking in Swift: Building the Swift Client, Part 4
Networking in Swift: Building the Swift Client, Part 5

This tutorial was authored by Stefan Agapie, a Senior iOS Software Engineer, and adapted for the present piece. 
Comments (1)

Tutorial: A Simple iOS Stopwatch App in Swift

In this tutorial, we will create a single view iOS application using the Swift programming language. The tutorial will provide some insight into basic usage of the Apple Xcode integrated programming environment, as well as the model/view/controller software architectural pattern. Our target audience are people who have some prior experience in application development and programming but who are relatively new to Xcode and iOS development. The project goal is to build a simple iOS stopwatch-style timer application designed for iPhone using Swift.

The app will contain two labels (one for our title and one for our numeric timer display), and two buttons (a start/stop button, and a reset button). We will first lay out our main view, which will contain these elements and then use the interface builder (i.e. storyboard) to hook our view into the controller (IBOutlets and IBActions). Finally, we will turn to the business logic of the app. In the end, we will have two imports and a view controller. We will add three methods to the view controller class: two actions methods and one helper method. The tutorial will be broken down into a series of just over thirty steps with screen caps to provide a quick visual aid.

The first thing you'll need to do, if you haven't already, is download the latest version of Xcode 6 (currently in beta as of this writing). If you are completely new to Xcode, you may find it difficult to navigate the interface. There are tons of great guides to Xcode that can be found online such as this one.

On initial startup, Xcode will present you with its ‘Welcome’ screen and offer several options. Select the “Create a New Xcode Project” panel from the window (see figure 1). If it does not present you with this screen, select File->New->Project from the menu bar.

Figure 1
On the following screen, select “Single View Application” and press the “Next” button (see figure 2).

Figure 2

Next, choose the options for your new project (see figure 3) and fill in the necessary fields as you wish, ex. project and organization names, and select “iPhone” as the device, since we are creating an iPhone app.

Figure 3
The following screen will then prompt you to provide a destination directory for your project. I like to keep current projects in a folder on my Desktop. There is also an option on the bottom of the screen to place your project under source control. If you don’t know what source control is or how to use it, then simply uncheck this box. (However, it is highly recommended that you invest some time learning about source control systems such as git.) Click “Next” once you have made your selections.

Your project should have opened to a screen similar to the one in figure 4.

Figure 4
From the device dropdown menu, located in the upper left corner, select iPhone 5s (notice also the other options that could have been selected here if we were planning to create a different app). See figure 5.

Figure 5

Now that we have our project’s initial setup completed, let’s get down to business! From the Project Navigator, select the Main.storyboard file. See figure 6.

Figure 6
In the Storyboard, select any view, then go to the File Inspector in Xcode’s right panel. Uncheck “Use Size Classes”, and you will be asked to keep size class data for: iPhone/iPad. Then click the “Disable Size Classes” button. Doing this will make the storyboard’s view automatically size with the selected device. See figure 7.

Figure 7
In the top left corner of Xcode, locate the “Play” button and press it to build and run your project for the first time. See figure 8. Upon a successful first launch of the project, you should see something like the image in figure 9, an iOS simulator. If you get any errors and the project does not build correctly, read the error report(s) carefully and see if you can troubleshoot the problem.

From the Object Library toward the bottom of the right panel in Xcode, select Label (figure 10) and then drag and drop it at the left style guide, but vertically centered into your single storyboard scene/view. See figure 11. The style guides are temporary visual placement lines that appear as you position view elements into your scene. This label will eventually provide the numeric display of our running stopwatch.

Figure 10

Figure 11

In order to make the label wider, we will select and drag the trailing edge of our Label element to the right of your scene until it meets the right most style guide. See figure 12.

Figure 12
From the Attribute Inspector panel in the right panel of Xcode, toggle the text alignment to center so our text appears in the middle of the label. See figure 13.

Figure 13
Go back to the object library and place two Buttons equally spaced apart about midway between the label and the bottom of our scene. See figure 14. These will function as our reset button and our start/stop button on the stopwatch.

Figure 14

From the Size Inspector in Xcode’s right panel change, the width of each button to 60 points. See figure 14.1.

Figure 14.1
Run your project to see what it looks like. Again, if you get any errors and the project does not build correctly, read the error report(s) carefully and see if you can troubleshoot the problem.

Select the Assistant Editor from the top right corner of Xcode to display the storyboard and associated Swift file side-by-side. Now hide both the Navigator and Utilities panels by clicking on the appropriate panel buttons in the top right corner of Xcode. See figure 15.
Figure 15
Now let’s connect up our storyboard elements to our controller, which will connect our interface to our code, that way all the relevant interface elements can communicate events to the controller.

Place your mouse pointer over the Label; then press and hold the control button while clicking and holding down your mouse button as you pan your mouse pointer across the screen and into the right side of Xcode where your Swift file is located. You should see a blue line follow your mouse pointer. See figure 16.

Figure 16

Once in the class area, as shown, release the mouse button and the control as well.  You will see a dialogue box prompting you for the name of your outlet. Name it ‘numericDisplay’. See figure 17. This will add the necessary outlet code to your Swift controller class. An outlet is a reference pointer to an element inside your storyboard. Creating outlets allows for easy access to objects in your storyboard. After naming the outlet, your screen should look like figure 18.

Figure 17

Figure 18

Go ahead and connect the buttons as outlets as well. Name the left button ‘resetButton’ and the right button ‘startStopButton’.

In a similar fashion to the newly created outlets, we will now create action methods for each button. This time we will drag the blue line toward the bottom of the file but inside the class body. Name the left button resetButtonPressed and startStopButtonPressed for the right button. In the dialog box, make sure you select 'Action' from the Connection drop down menu. See figure 19. Action methods are the functions in your class that get messaged/called when the button that is associated with the connected method is triggered by an event. An event is initiated when the user interacts with any of your buttons.
Figure 19
Your interface should now look like the screencap in figure 20.

Figure 20

To accurately update our numeric display label, we need to tie it in to a mechanism that will update at very precise time intervals. To access this functionality, we need to import the appropriate class library. From Xcode’s menu bar, select the Window tab drop down menu then select Documentation and API Reference. See figure 21. The documentation search window should appear. In the search bar type CADisplayLink and locate the appropriate documentation. Read through the documentation and familiarize your self with the CADisplayLink class. This class is very useful when your code needs precise timing control.

Figure 21

Notice that the CADisplayLink requires the QuartzCore framework. A framework is a set of classes with predefined functionality so that you don’t have to reinvent the wheel; it's code packaged for re-use, so use it!  With Swift you no longer need to define an interface(.h) and an implementatin(.m) file to define a class which is nice. Also, when importing different frameworks into your project you no longer have to go Xcode's build setting and explicitly add that framework; it automatically loads when you use the keyword import followed by the desired framework like so: import {SomeFramework} but without the curly braces.  And my favorite addition is the fact that semicolons are no longer required! WhooHoo! There are also a ton of outher features of Swift that I have yet to discover. In your ViewController.swift file add the line of code importing QuartzCore:

Importing a framework into your file gives you access to its classes and functionality. In your ViewController class, add the following var properties just below the @IBOutlet properties. Add the code in lines 5 and 6 below:

‘var’ is short for variable and displayLink is our object pointer of type CADisplayLink. We use this pointer to hold a strong reference to an instantiated CADisplayLink object that we will create in a few moments. We want a strong reference to an instance of CADisplayLink to be able to access it throughout the various parts of our class. We also define a lastDisplayLinkTimeStamp of type CFTimeInterval. This variable will store a running tally of the total elapsed time.

Now let’s set the default view element values for our numeric display label and our two buttons. Add the code below to our viewDidLoad() method:

In your viewDidLoad() method now add the lines of code from the snippet below:

The first new line of code above (line 16) creates an instance of a CADisplayLink object, and assigns this class, i.e. “self,” as the target for messages that inform us of a display refresh rate update. This occurs in the first parameter of the CADisplayLink(<first parameter>, <second parameter>) method call. In the second parameter we pass the name of the method that we would like to be called when there is a display refresh rate update. We will define this method shortly. The second new line of code (line 9) ensures that the display link does not begin its updates until we press the Start button in our user interface. The third new line of code (line 12) schedules the display link to begin sending notifications to our instance method about display refresh rate updates. The fourth new line of code (line 15) simply initializes our elapsed time running tally variable.

The next step is to define the method that will be called when the display link has an update. Add this code to the bottom of the viewController.swift class, i.e. inside the final class curly brace:

Now for the logic—we are almost there! In the newly created function add the following lines of code:

The first new line of code (line 3) updates our running tally. The second (line 6) formats our running tally into a string that only shows the last two significant digits. The third (line 9) updates our numeric display label.

Let’s move over to the startStopButtonPressed(…) method. This method is called anytime the user presses the button situated to the right in our stop watch scene. When this button is pressed we want to toggle the display link’s “paused” Boolean value. Add the following line of code to this method.

At this point you can run your project and press the start button to see your stop watch in action! Woohoo! Again, if you get any errors and the project does not build correctly, read the error message(s) carefully and see if you can troubleshoot the problem.

Let’s shift our focus to the Reset button. What do you think this button should logically do? It should pause the display link to prevent it from  sending us any further updates, then set the numeric display label to zero, and update our Start/Stop button state. In the resetButtonPressed(…) method add the following lines of code:

Let’s now complete our code project by adding the last few lines of code for our Start/Stop button. In startStopButtonPressed(…) add the code in bold:

Our label text string will not be modified if our code does not fall through our first conditional if statement. If, however, the display link is paused, then we check the running display link tally. If this tally is greater than zero, then we display the resume button since pressing this button again will not reset our running tally. If it’s equal to zero then we display the start text. The button text is set in the last line of code.

Your final ViewController file should look like this.

Finally, let’s add a title label. Go back to the main storyboard. From the object list at the bottom of the File Inspector in the right pane of Xcode, drag a Label to the center/top of your main view. Size it as you like, and provide it with a text title such as “Stopwatch”.  The final product should look something like the three screencaps below, showing the default, running and paused states:

Default State



And that concludes our simple Stopwatch app tutorial! We leave you off with a question for further reflection.  Notice that our chronometer output is not formatted for standard time. Our implementation increments our minor units, values to the right of the decimal point, from .00 to .99 before increasing the the major unit by one. Although this is a correct unit of measurement, it is not in the ubiquitous standard time format. In the standard format the minor unit, a.k.a the second, is incremented from .00 to .59 before the next major unit, i.e. a minute, is increased by one. Since there are many ways to implement this, some being more efficient than others, we leave this consideration to the reader as an exercise. Post your own solution below. And, as always, feedback, suggestions, and angry tirades are welcome in the comments.

This project can be found on GitHub.

The Stopwatch app and tutorial was originally authored by Stefan Agapie, a Senior iOS Software Engineer, and then adapted for the present piece.
Comments (6)

Python: What to do after you've finished Code Academy?

One of the most common beginner questions I see in Python programming forums is from people asking what to do once they’ve completed Code Academy’s Python training course. The possibilities are virtually limitless and may seem overwhelming at first, especially if you have little prior programming experience. It’s a bit like finding yourself in a foreign country where you know enough of the local language to just get by, but not enough to really find your way around. I certainly don’t claim to have the map, but in this post I’ll try to point out a few landmarks that might help some folks get their bearings. 

The Code Academy course covers the basics of Python syntax and data structures, and provides a quick introduction to more advanced topics like the use of list comprehensions, bitwise operators, classes, file input/output etc. Along the way, the student also completes a handful of small projects to demonstrate how this newly acquired knowledge can be put to use, for example, a pig latin translator, a Battleship game simulator and so on.

But the big question is: what next?! There is no straightforward answer to this question, as it depends on a number of highly individual variables such as your level of prior programming knowledge and experience, your interests, your goals and motivations for learning programming in general and Python in particular, not to mention the amount of time you are able to devote to study and practice, to name just a few. For the sake of simplicity, what follows is targeted to a beginner who has recently completed an introductory Python crash course such as Cody Academy’s Python Track, or Learn Python the Hard Way, has little or no prior programming experience, and can devote a modest amount of time to study and practice on a regular basis. 

As a natural language instructor, I can almost always tell when a student has not done any homework or practice over a long weekend: they are already starting to get rusty! Probably the single most important thing to do after an introductory course like Code Academy’s is to reinforce the lessons learned, and to do it on a consistent basis. This will help to shore up all that newly acquired knowledge and provide a sturdier basis to extend it and expand on it. This could be anything from reading a textbook to watching a series of lectures, or following along with another tutorial, exploring other areas of the Python universe, tinkering with your own little programming projects, or some combination of these, or even all of the above. 

You’ll likely also find that these activities are themselves mutually reinforcing: while working on your own projects, you’ll realize when you’ve hit a wall and need to consult some documentation or a textbook, or seek out a new library or framework to help achieve your goal; reading through a textbook you’ll be exposed to new ideas that you can experiment with in the interpreter or in your own little projects; working through a tutorial, you might find a piece of code that interests you and which you start to tweak on your own to see how it works and to experiment with extending it or expanding on it in some way, shape or form.  

If Code Academy was your first exposure to programming in general, it might be a good idea to consider working through a general introductory textbook (or even an introductory course!) on computer science. This will provide you with a basis in the fundamentals of the discipline as a whole, things that are more or less the same across all programming languages. 

So far as introductory textbooks go, many people, myself included, highly recommend Think Python: How to Think Like a Computer Scientist, which is freely available online.   This book is required reading for a number of well known introductory computer science courses such as MIT’s Introduction to Computer Science and Programming, and was written for the express purpose of introducing students to the field. It is highly readable, provides a review of basic syntax and covers intermediate as well as more advanced topics, along with a series of chapters on object-oriented programming and design. 

Along similar lines, if you have the time to devote to it, I highly recommend MIT’s Introduction to Computer Science class. All the lectures, recitation sections and course materials are freely available online in their entirety, and the course uses Python as its pedagogical language of choice. For more information on this course, see our previous post Teach Yourself Python in Less Than Four Months, which provides a learning plan that uses the MIT course as its guide.  

Okay, but what if you are not the type who likes to curl up with a good textbook, and don’t have the time to slog through a college level introduction to computer science course, but want to delve more deeply into Python itself? What then? In this case, you might consider working through another general introductory tutorial on Python programming, this will help consolidate the knowledge you’ve already gained and also likely expose you to more beginner and intermediate level aspects of the language and the programming process. There are tons of such resources available online. Here are a few that I've found quite helpful:
"Bah," some may say, "I'm bored of mechanically typing out tutorial code! I want to experiment, but I'm not sure where to begin!" Not to worry, there's tons of stuff out there, you just have to know where to look. For those who want to jump right in to real problem solving, your first stop should be the Programming Mega Project List. This is a list of around 100 practical programming projects that can be solved in any programming language. The difficulty level of the various projects ranges from beginner to advanced and the list broken down into basic categories such as math, algorithms, networking, text, web, and so on. Find one that interests you, tackle it and repeat.

Other people may find it rather uninteresting to solve problems for the sake of problem solving, and would rather explore Python itself. The standard library is your friend! One of the great things about programming is that it can make your life a whole lot easier. If you stick with programming, one thing you will learn rather quickly is that programmers are lazy and proud of it. If I had a dime for every time I’ve come across a talk or article on programming which proclaimed that programmers are lazy, I’d probably have like $10 by now.  I guarantee there is some absurd, repetitive task that you have to complete on a regular basis that can be automated with a relatively simple Python script. For these everyday routines, there is also very likely a standard library module that can aid you in your endeavor. Relevant xkcd:

Maybe you work in an office and have a tedious spreadsheet task you have to complete on a regular basis. Automate it with the csv module. Perhaps you’re in a band and hate writing up set lists, write a random set list generator with the random module. Maybe you like sports or finance, and are constantly looking up scores or quotes. Write a command line app to grab them from your favorite online source using urllib without having to open a browser.  If you’re a news junky, you could consider writing your own RSS headline aggregator with urllib and one of the XML modules. The possibilities are literally limitless. 

Last but not least, as a beginner Python programmer, you will most definitely want to begin checking out the many great frameworks that have been built around the language.  "A software framework is a universal, reusable software platform to develop software applications, products and solutions," says Wikipedia. At the most basic level, a software framework is a library or set of libraries that provide generic functionality for routine tasks to aid in the development of applications and programming projects. In the Python universe there are tons of frameworks to explore, such as web frameworks for the development of web applications, GUI frameworks for development of graphical user interfaces for desktop applications, and so on. Some of my favorites:
Well, that concludes our tour of some noteworthy landmarks in the Python programming space. As always, feel free to provide your own favorite resources or suggestions in the comments.
Comments (3)

Unit Testing and Test-Driven Development in Python

There are both advantages and disadvantages to being self-taught in any given discipline. In certain cases, the advantages and disadvantages can overlap or even coincide. For example, when you are self-taught, you are not confined by institutional structures and courses of study. On the one hand, this allows for a distinct measure of freedom to pursue one’s own interests in the field, which would not necessarily be afforded to a person following a traditional disciplinary curriculum. On the other hand, this also means that it can be quite easy to develop gaps in one’s basic knowledge of the discipline, for the simple reason that these areas of study did not fall within your area of interest.

I discovered one such gap in my study of programming in general, and Python in particular, a number of months ago when I came across a quote online that went something like this: “Code that is not tested is broken by definition.”  Testing? “You mean running the code to see if it works?” I thought to myself. Within the next hour I had my first exposure to the method of test-driven development and the Python unittest module.

This was literally the exact opposite of how I had approached my own programming projects up until then, which might be termed “error-driven development”: write some code; run it; see if it works; if it doesn’t work, tinker at random until it does; write some more code and repeat. I quickly realized that, according to the above quote, all my code was broken, by definition. 

The test-driven development model is the reverse of this: write a test, run it and watch it fail; write some code to make the test pass; refactor; write another test and repeat. It was an enlightening experience to attempt writing even a simple program under a test-driven model, as it was immediately obvious that I had only the vaguest notions about things that I thought I knew fairly well.

Since then, I’ve re-written a number of programs I’d created for myself under a completely test-driven developmental model, and have integrated testing into my everyday coding practice. I’ve also collected a bunch of resources that I've found helpful along the way, which you can find below. Also, as you may know, of late there has been something of a controversy brewing on the merit and value of test driven software development. Some links on this are supplied at the end. As always, further recommendations are welcome in the comments!

Overview of Test-Driven Development (Video Lectures)

Unit Testing in Python (Video Lectures)

Python Unittest Module Docs

Python Unittest Intro Tutorials

Test Driven Development in Python

Unit Testing Today

Comments (4)

An Interview With Al Sweigart, Author of Three Introductory Books on Python

Albert Sweigart is a software developer who lives in San Francisco.  To date he has published three introductory books on Python, all of which can be downloaded for free from his website Invent With Python.  Readers may recall the review of his most recent book, Hacking Secret Ciphers with Python, that I posted here last month, which was one of the most popular posts to date here at the aGupieWare blog.  Over the weekend, Al was kind enough to answer a few questions via email for an interview.  

Q: First, thanks for taking the time for this interview. Could you tell us a bit about yourself and your programming background? 

A: I started programming in BASIC when I was in the 3rdgrade, which I always hate to say because it makes people believe that you have to start programming at a young age to become proficient in it. All of my programs up until college were pretty much variations of the same program. I didn’t really teach myself all that much, and these days anyone could do in a few months what I did in those several years.

Q:  You've published three introductory books on Python, all of which are available on your website  The first two, "Invent Your Own Computer Games with Python", and its sequel, "Making Games with Python and Pygame," are geared toward kids, while the third, "Hacking Secret Ciphers with Python," seems to be intended more for an adult audience.  How have the three books been received? 

A: Altogether, the books seemed fairly well received. I was surprised that people liked my first book, which led me to continue writing. The Amazon reviews are almost exclusively 5 and 4 stars, and I get an occasional Thank You email from readers. “Hacking Secret Ciphers with Python” is probably a bit much for young kids, but I think teenagers and adults would be able to digest it.

Q: Do you see the cryptography book as a step in a different direction, or as an extension of the puzzles and games introduced in the earlier works? 

A: I saw it as a different direction. Video games are a great way to get people involved in programming, but I wanted something else as well. I noticed that there were a lot of code and cipher books that talked about the classical ciphers the book covers, but very few that explained how to break them and none about how to write programs to break them. I saw it as an opportunity to reach a broader audience. The book itself is also aimed at people with absolutely no prior programming or cryptography experience.

Q: What has drawn you to python?  What do you think are its strengths and weaknesses?   
A: Python is a very readable scripting language. Unlike Perl which has very obtuse use of punctuation characters for different language features, and unlike Java which has an overwhelming amount of boilerplate code, Python seems to be a very direct, “get it done” language. It also has a very gentle learning curve. I’ve written a blog article before about how Python isthe new BASIC.  I use Python for both my own software projects and for teaching programming. At this point, I’ve become so accustomed to Python and its idioms that I’m afraid I’ve become blind to its weaknesses, so I really couldn’t think of any.

Q: What are your favorite python modules?

A: Pygame is excellent for creating games and 2D graphical applications. I’ve written a couple modules that work on top of Pygame called Pygcurseand Pyganim, which add a curses-console for text games and sprite animation, respectively. Lately I’ve started using Requests and Beautiful Soup for downloading and parsing web pages for my Python script. (I’ve written a simple Reddit bot that automatically checks several different web comics and posts them to the r/comics section of the site.) I have some experience with wxPython for creating GUIs for traditional desktop apps, but I’ve heard good things about Qt bindings for Python as well.

Q: Do you currently have any new python books in the works?

A: I’m writing a new Python-for-beginners book with NoStarch Press, which tentatively has the title “Automate with Python”. I’ve described it as “a programming book for people who don’t want to become software developers”. I noticed a lot of office workers, administrators, and academics do a lot of computer-based tasks that involve a lot of mindless, repetitive clicking or compiling of data. This book aims to teach them just enough programming so that they can automate these tasks. It covers basic Python, and then goes into several different modules for text parsing, web scraping, moving and renaming large amounts of files, updating spreadsheets, or sending automated emails and text message alerts. I’m hoping to have it available by summer of 2014.

Q: You accept bitcoin donations through your website.  Have you worked on, or are you currently working on, any Bitcoin related projects?  Can you speak to the intersection of Bitcoin and Python? 

A: I had only added it to the site after other people on the internet suggested it, but I’m glad I did. As with many people, bitcoin had been in my periphery for a while. But setting up the wallet for the donation link forced me to learn more about it. Although as of yet I haven’t worked on any bitcoin projects (if anything, the Tor Project will get my focus once I’ve finished the next book). But for all the negative publicity that bitcoin gets regarding its use to buy drugs and illegal things (all of which, by the way, can apply to cash) I’m really excited about it. It allows minors and people in third world countries to conduct commerce over the internet, and that is a Big Deal.

As to Bitcoin and Python, I think that having a new ability to receive and send money over the internet without middlemen (e.g. Visa) along with open source software like Python really lowers the barrier-to-entry for software development outside of America and traditional software-producing strongholds.

Q: Like your other works, the cryptography book can be read online or downloaded for free.  But if a reader purchases it, you donate all proceeds of the book to the Electronic Frontier Foundation, Creative Commons and the Tor Project.  Why did you decide to donate the proceeds for the book on cryptography?

A: It was the suicide of Aaron Swartz, to whom the book is dedicated to, that made the decision for me. I hadn’t met Aaron, though I have friends who were friends of him. His passing was a tragedy, but also a wake-up call for myself. Looking at his life really made me start looking at mine and how I wanted to make contributions like he had. At the time I was, after two years of off-and-on writing, a couple months away from finishing “Hacking Secret Ciphers with Python”. The other books were selling well, and I had a day job that gave me a comfortable middle-class lifestyle. So I decided that I would turn the proceeds from the books over to help organizations that are doing some really wonderful and necessary things to protect the internet.

Q: What advice would you give to young and not so young beginning programmers?  

A: My main piece of advice is that you suck at coding and will continue to suck for the rest of your life. Once you’ve accepted that, you’ll be able to move on and write some interesting software. Don’t worry about the nagging feeling that you aren’t good enough or know enough, because that feeling will be permanent no matter what you do. And if it doesn’t, it’s because you’ve given up on forcing yourself to learn new things (which is the real danger.)

Also, you’re never too old or too bad at math to learn to code. Most programming doesn’t even require mathematical knowledge beyond arithmetic, and unless you’re in your sixties or seventies you aren’t even too old to become a professional software developer. Programming isn’t something that requires you to be a super genius to do. More than anything, having an interest and motivation to act on that interest is all you need to be set on the right path.

Q: Thanks for taking the time to answer our questions!
Comments (3)

Book Review: Hacking Secret Ciphers with Python

Hacking Secret Ciphers with Python is a free introductory textbook on cryptography, computer programming and the Python programming language written by Albert Sweigert, a software developer from San Francisco.  Hacking Secret Ciphers with Python is Sweigert's third book on Python, and the first that teaches the programming language through cryptography and traditional cryptographic protocols.

Published under a creative commons license, the work can be read for free online, downloaded as a .pdf or purchased from Amazon, with all proceeds going to the Electronic Frontier Foundation, Creative Commons and the Tor Project.  From the book's description:
“Hacking Secret Ciphers with Python” teaches complete beginners how to program in the Python programming language. The reader not only learns about several classical ciphers, but also how to write programs that encrypt and hack these ciphers. The full source code is given and explained line-by-line for ciphers such as the Caesar cipher, transposition cipher, simple substitution cipher, multiplicative & affine ciphers, Vigenere cipher, and hacking programs for each of these ciphers. The final chapters cover public key cryptography and the modern RSA cipher.
Clocking in at 416 pages, the book is broken down into 24 chapters covering virtually everything from the ancient Caesar Cipher to modern public key cryptography.  It thus provides a practical overview of the history of cryptography, while simultaneously introducing the reader to progressively more advanced aspects of the Python programming language. 

The book begins at the beginning, showing the reader first how to create rudimentary ciphers with paper and scissors.  It then gives a quick introduction on how to install Python, how to work with the interactive shell, and provides a quick overview of Python basics before jumping in to its first major coding chapter on the Reverse Cipher.  For each cipher covered in the book, it provides the Python code to run that cipher, followed by a chapter covering a second program that can be used to hack that cipher.  Python basics are covered in the analysis of the code used to create and then hack the given cipher.

Highly recommended for beginner to intermediate Python programmers who are interested in cryptography.  And since it is available free online, you can dive right in.

Online Learning: Three Free Introduction to Computer Science Courses

These days, with a bit of perseverance and discipline, it is entirely possible to receive a world class education in computer science for free online from the comfort of your own home.  Many of the top computer science departments at US universities make their course lectures and materials freely available on the net, providing motivated individuals with a range of choices that is almost unbelievable in its scope.  In this post, we'll take a look a three Introduction to Computer Science courses that have been made freely available online from Harvard, MIT and Stanford.  The Harvard course provides an introduction to C, PHP and JavaScript.  Stanford focuses on Java. And MIT utilizes the Python programming language. 

Harvard's Intensive Introduction to Computer Science
Course site and description:
This free online computer science course is an introduction to the intellectual enterprises of computer science. Topics include algorithms (their design, implementation, and analysis); software development (abstraction, encapsulation, data structures, debugging, and testing); architecture of computers (low-level data representation and instruction processing); computer systems (programming languages, compilers, operating systems, and databases); and computers in the real world (networks, websites, security, forensics, and cryptography). The course teaches students how to think more carefully and how to solve problems more effectively. Problem sets involve extensive programming in C as well as PHP and JavaScript.
Stanford's Introduction to Computer Science and Programming Methodology
Course site and description:
This course is the largest of the introductory programming courses and is one of the largest courses at Stanford. Topics focus on the introduction to the engineering of computer applications emphasizing modern software engineering principles: object-oriented design, decomposition, encapsulation, abstraction, and testing. 
Programming Methodology teaches the widely-used Java programming language along with good software engineering principles. Emphasis is on good programming style and the built-in facilities of the Java language. The course is explicitly designed to appeal to humanists and social scientists as well as hard-core techies. In fact, most Programming Methodology graduates end up majoring outside of the School of Engineering. 
MIT's Introduction to Computer Science and Programming
Course site and description:
This subject is aimed at students with little or no programming experience. It aims to provide students with an understanding of the role computation can play in solving problems. It also aims to help students, regardless of their major, to feel justifiably confident of their ability to write small programs that allow them to accomplish useful goals. The class will use the Python programming language.  Many of the problem sets focus on specific topics, such as virus population dynamics, word games, optimizing routes, or simulating the movement of a Roomba.
Comments (2)

PHP vs. Python vs. Ruby

From Udemy, here's an interesting infographic comparing PHP, Python and Ruby according to a few different metrics:


Programmers Beware: Any Code You Write May Be Used Against You in a Court of Law

From Wired:
In a criminal case sure to make programmers nervous, a software maker who licenses a program used by online casinos and bookmakers overseas is being charged with promoting gambling in New York because authorities say his software was used by others for illegal betting in that state. 
New York authorities say that about $2.3 million that Robert Stuart and his company, Extension Software, received in cash and money orders for licensing his software constitutes direct proceeds of illegal, U.S.-based bookmaking operations. . . .

“It’s overreaching where they’re going after a software developer who sells the software with a legal license, and yet we’re still being prosecuted on how it’s being used,” Stuart says. He notes that authorities have not told him yet who exactly he’s accused of aiding and abetting.
It appears the government is prosecuting Stuart because he refused to be blackmailed by New York State authorities:
Stuart asserts that New York authorities only came after him because they wanted to use him as a conduit to uncover illegal gambling operations in that state. He says the New York district attorney’s office tried to strong-arm him into a plea agreement that would have had him hacking into the systems of his software clients in order to obtain the usernames and passwords of gamblers and their bookmakers to help authorities gather evidence of illegal gambling. 
Although Stuart initially agreed to the terms of the plea, he later recanted because he said he was uncomfortable being used as a pawn to secretly collect information on his customers. He claims authorities are charging him now in retaliation for refusing to cooperate with them.
Comments (1)
See Older Posts...