Nicole Harris

Talking about PyPI on podcast.init

2019-08-21T00:00:00+01:00

A big thank you to Tobias Macey for hosting us.

You can listen to the episode below, or by visiting the podcast.__init__ website, where you will also find the show notes.

EuroPython Keynote - PyPI: Past, Present and Future

2018-07-26T00:00:00+01:00

In July 2018, I was honoured to keynote at EuroPython - the largest European conference for the Python programming language, with over 1,100 attendees.

My talk explored the past, present and future of the Python Package Index (PyPI), a project I have been working on for approximately 3 years. This post documents the video, slides, links, resources and statistics resulting from that presentation.

I would like to thank the organisers for the opportunity to present, and the audience for their warm response.

Video

Or watch on YouTube

Slides

Links and Resources

On Python Packaging

Python Packaging Working Group: a sub-body of the PSF dedicated to raising funds to advance the state of Python packaging. You can donate to this group here.
Python Packaging Authority: a group of developers who maintain major Python packaging projects (including PyPI). This group also maintains the Python Packaging User Guide which is the authoritative guide to Python Packaging. PyPA projects can be found on GitHub. There is also a really interesting history of Python Packaging in the PyPA documentation.

On PyPI / Warehouse

pypi.org: the web interface for the Python Package Index
Warehouse: the codebase currently powering PyPI. If you’d like to contribute, please visit our issue tracker. Issues set aside for new contributors are found here.
PSF announcement of MOSS award: Details of the award from Mozilla that funded Warehouse development between Dec 2017 and May 2018.
Powering the Python Package Index: an article from Donald Stufft (PyPI / Warehouse maintainer) that discusses what it takes to power PyPI. This article is now slightly out of date (as the figures have grown over the past two years), but is still a very interesting read.
“A new package index for Python”: LWN.net article from Sumana Harihareswara (Warehouse project manager) covering the past, present and future of PyPI.
“Markdown Descriptions on PyPI”: article from Dustin Ingram (PyPI / Warehouse maintainer) on the steps required to enable Markdown on your PyPI project descriptions
I have also published a number of articles about the Warehouse project, covering design objectives, user testing, accessibility and user research

Statistics

I used infogram to generate the graphs for my presentation. Happily, these can also be embedded:

Bar Chart
Infogram

Images

Thanks to Alina Cristea, the official conference photographer, for taking the following images:

Image by Alina Cristea. View on Flickr

Image by Alina Cristea.

Thanks!

I’d like to extend a big thank you to the following people:

The EuroPython organising team for giving me the opportunity to present
Ee W. Durbin III, Dustin Ingram, Donald Stufft and Sumana Harihareswara for digging up facts and figures for my presentation and for being great co-contributors on the Warehouse project
Aina Requena Lafuente for the lovely illustrations
My colleagues at PeopleDoc for reviewing my presentation
All packaging contributors - past, present and future :)

Addendum (6th Aug, 2018)

Since presenting my keynote, Ee has dug up some more information on PyPI’s history, so I thought I’d share it here:

The original Python Package Index was born on Friday, the 1st of November 2002, with both the original commit and first package uploaded on that day. The first upload was for the roundup project - the codebase that still powers bugs.python.org
The Index was moved from the “Dinsdale” server in Holland to the Oregon State University Open Source Lab on the 14th of August, 2012

Thanks Ee!

PyPI User Research

2018-07-22T00:00:00+01:00

Along with user testing, user research is an important part of developing robust user experiences. Truly understanding your users - what motivates them, what they want, and how they use your product or website is essential for making better design decisions.

Conducting User Research for PyPI

As PyPI is an open-source project we don’t have the time (or money) to conduct individual user interviews, develop user personas, deeply analyse our Google Analytics data, or run discovery workshops with PyPI users. In the short-term, it’s necessary to find a way of collecting information about what the community wants, using a method that is fast, low-cost and engaging.

Currently, the page that we’d like to improve the most is the project detail page (view example). This page contains an invidual project’s README, history, files and other data. It is the most visited page type on the site and the interface we receive the most design feedback about.

Depending on the project, there can be a lot of information on this page. To maximise the potential of our redesign, it is important to understand how much our users value each piece of information in relation to the rest of the content.

Approach

To discover what the community thinks, I set up a “Buy a Feature” form. This form was based off the “Buy a Feature” game that is typically run as a workshop.

The idea was to price each feature on the current page according to the space it takes up on the screen and then allocate a limited budget to each participant. Participants then use that budget to buy the features they want to see. I also added a wildcard item, to allow community members to request new features. The resulting data should indicate the overall priorities of the research participants.

The beginning of the "Buy a Feature" form filled by research participants. In total, there were 18 features available to buy, each priced relative to their size.

Limitations

No research method is perfect, and there were certainly limitations to this exercise:

Both the pricing and the budget were subjective.
Participants may have chosen a lower priced item to use all of their allocated budget, even if this item was not their ideal choice.
As the Google Form contained no budget validation, we relied on trust (and good mathematics!) to ensure participants didn’t overspend their budget.

Results

In total, 1,926 people participated in the exercise. Here are the results:

Participants = Total number of participants who selected this feature
Percentage = Percentage of participants who selected this feature

Feature	Participants	Percentage
Project description	1466	76.19%
Required Python version	1349	70%
Links to project online	1337	69.4%
Date project last updated	1235	64.1%
Licence	1059	55%
Project name and release no.	1001	52%
Version status	854	44.3%
Release history	813	42.2%
GitHub statistics	780	40.5%
Project summary	752	39%
Requires distribution	647	33.6%
Download files	638	33.1%
Author	619	32.1%
Tags	461	23.9%
Trove classifiers	441	22.9%
Maintainers	424	22%
Statistics instructions	266	13.8%
Wildcard (new feature)	157	8.2%

"Buy a Feature" - PyPI research
Infogram

157 people chose to purchase a wildcard item - meaning that they forfeited some of their budget to request something different. I am in the process of moving these suggestions into our issue tracker. The full list can be viewed here.

Next Steps

In the coming months, we will continue to conduct user tests to qualify the results of this research, and identify flaws in the current interface.

After this, I will work to propose a new interface that responds to our discoveries, in an effort to better serve the Python community.

Accessibility on Warehouse (PyPI)

2018-05-17T00:00:00+01:00

This year Global Accessibility Awareness Day is being marked on May 17th. The purpose of this day is to raise awareness about digital inclusion - and how people who work in the digital space can ensure their software works for the largest possible group of users.

Accessibility is an important subject; as a digital designer, it is my responsibility to do everything that I can to design solutions that include, rather than exclude, users.

On the Python Package Index, accessibility has been baked into the design from the beginning: from the selection of high-contrast colors, to the large default text size, to the way that our HTML markup is structured. However, like everything, meeting accessibility standards and including all users regardless of their impairments is an ongoing task that will never be complete.

To that end, earlier this year, I contacted Axcess Lab to ask if one of their team members would be interested in dedicating some of their awesome open-source project time to the Python Package Index. Lucky for us, Mattias volunteered to assist, and has since completed an accessibility audit on pypi.org (thanks Mattias!!!).

You can read the full audit here, a few highlights:

What we’re doing well

Mattias noted font size, color contrast, outline design and the uncluttered UI as positive accessibility attributes.

Our form design is helpful for users using screen readers, while visually impaired users are able to zoom the interface without loss of function.

On mobile, the whitespace we provide between elements helps users with motor impairments scroll the page.

Improvements

There are still a few things we can do to make the user experience better for all:

Redesigning the line length of our text, for optimal readability
Removing italic styles, as these can be difficult to read for people with reading impairments
Reconsider our use of disabled buttons, because they suck.
Underlining links
Increasing the clickable areas of some elements
Adding ARIA where needed
Improving the way some of our forms work, particularly for people using screen readers

Next steps

I have started opening tickets on the project issue tracker to address each of these issues, and will begin working through these in the coming months.

I will also be running a PyPI sprint at EuroPython this year, so hope that any remaining issues can be addressed at this time.

How you can help

If you are a PyPI user and notice an accessibility issue on the site, please report it via our issue tracker. We take these issues seriously, so will try our best to respond as soon as possible.

If you are a developer, and would like to help make the Python ecosystem a more friendly and welcoming place, we’d love you to make a PyPI PR addressing an accessibility issue. We do our best to support new contributors - just comment on the issue you’d like to work on, and let us know if you need any help

Addendum - 21st July 2018

The Python Packaging Working Group continues to seek funding to improve PyPI. With more funding, the team aims to make the accessibility improvements highlighted by this audit, as well as identify and address other accessibility issues. To donate to the working group, visit donate.pypi.org - donations can be made on a single, or recurring basis. Every donation is appreciated!

My guest appearance on the Talk Python to Me podcast

2018-04-27T00:00:00+01:00

A big thank you to Michael Kennedy for hosting us!

Check out the recording here or view the transcript.

User Testing Warehouse

2018-03-13T00:00:00+00:00

User testing is a user experience methodology that places the user at the center of design decisions. UX professionals conduct user tests to challenge their design concepts and validate that the UI works as they intended.

User tests typically involve asking a target user to carry out a series of real world tasks on the UI. Testers can then identify problems in the UI - where the user gets lost or confused, or can’t work out how to complete the assigned task.

Any identified problems can then be raised as design issues for the team to fix.

User Testing Warehouse

It had always been my intention to run user tests on the Warehouse project, but it wasn’t until the project received MOSS funding that I was able to dedicate the amount of time required to set up and conduct these tests.

Having recently completed the pages for logged in users (account settings, manage projects, etc.) these pages seemed like the best candidates for our initial round of testing.

The test I constructed was simple: asking users about their current use of PyPI, then requesting them to complete a series of tasks on the new management pages. For the test, I recruited users who were package owners or maintainers - i.e. people who had experienced the old user interface and who would understand my instructions.

Over three weeks, I ran tests with six different users, with each test taking between 25 minutes and one hour, the duration depending on how much the test subject had to say.

As expected, the tests highlighted a number of problems in the UI, which in turn prompted me to open or tag 20 issues in our issue tracker. The vast majority of these tickets are simple changes that have been tagged as good first issues - which should in turn help with our efforts to reach out to new contributors.

Several of the test participants also raised new ideas, for which I will open new tickets soon.

In total, this round of testing took 15 hours - encompassing writing the testing script, recruiting users, running the tests, and opening related tickets.

A big thanks to Ee W. Durbin III, Nicolas Dubois, Łukasz Langa, Russell Keith-Magee, Alex Chan and Eliot Berriot for participating in these tests.

Next Steps

From this intial program it is clear that user testing can bring value to the Warehouse project. The challenge is to continue to conduct such tests once our MOSS funding is depleted.

Fortunately, the Python community is engaged with the project, and, so far, we’ve had no problems recruiting test participants. Usability experts recommend a minumum of 5 users per test, so as long as this goodwill continues, I don’t anticipate running out of test subjects.

On the other hand, setting up and running user tests takes time; and it would be nice to have some help with this to lighten the workload (and increase our testing bus factor). For this reason, today I’ve put out a call to train up to three people on how to conduct and run user tests. My hope is that this opportunity will be taken by students (or UX enthusiasts) as a way to build their experience by working on a live, widely used application.

Should this program be successful, I’d like to start group testing the project detail page in the coming weeks. This page is the most important on the site, and coincidentally, the page we’ve also received the most feedback about.

With more funding, it would be possible to extend our testing further to encompass testing the UI for accessibility and internationalisation.

Get Involved

So, how can you help?

Firstly, if you are a developer, please consider contributing to Warehouse. Right now, we have lots of tickets marked as good first issues in our issue tracker. Because of our MOSS funding, we are also able to be more responsive to your questions and provide you with more support to get started. If you’re planning on attending PyCon North America, or EuroPython, our team is planning on running conference sprints - this is a great opportunity to hack with members of the team and work with others on the project.

If you are interested in learning how to conduct user tests, please fill out this form. If you have any questions about what’s involved, you can also email me directly at n.harris[at]kabucreative.com.

Finally, if you’d like to volunteer to be a test participant, please fill out this form.

Interview Series - UX & UI at PeopleDoc

2017-08-10T00:00:00+01:00

As part of my work at PeopleDoc, I was recently interviewed by Nicole Lindenbaum on our approach to UX and the development of PeopleDoc UI - our internal design system.

The interview was split into three parts:

A big thanks to Nicole for organising and publishing this content!

Presenting Warehouse at PyCon France

2016-10-16T00:00:00+01:00

The talk explored the organisational state of Python packaging, the current state of the Python Package Index, and introduced the Warehouse project - the codebase that will soon power PyPI.

I’d like to thank the organisers of PyCon France for the opportunity to speak to such an engaged audience and for delivering an excellent conference overall. Special mention to all those French speakers who, during the conference, patiently corrected my stumbling French and helped me build my vocabulary.

The organisers of PyCon France have put together a fabulous video that combines the video of the talk with the slide display. If you’d like to view the talk, this is the best format.

I’ve also embedded the raw video and slide presentation here for posterity. Enjoy!

Or watch on YouTube

Presenting at DjangoCon Europe

2016-04-16T00:00:00+01:00

Imagine this you’re on stage and you have a captive audience of 300+ people. That’s the view I faced just a few weeks ago, as I presented ‘Learning Django, Learning French’ (an extension of my ‘Learning Django, Learning French’ talk) to the audience at DjangoCon Europe 2016.

You can judge for yourself the success of my talk - in any case, I’d like to thank the organisers of DjangoCon Europe for having me on stage. I’d also like to thank those community members who gave me so much positive feedback and made my conference experience great!

Or watch on Opbeat

All of the videos for the conference can be found on Opbeat’s website. In particular, I’d like to highlight the talk by Erik Romijn and Mikey Ariel entitled “Healthy Minds in a Healthy Community” as an important message for everyone trying to find a healthy balance working in open source.

Designing Warehouse - An Overview

2015-12-31T00:00:00+00:00

For the last six months, I have been working with the Python Packaging Authority (PyPA) to design Warehouse - the new codebase that will soon replace the Python Package Index (PyPI).

This article is an attempt to explore our objectives and challenges, provide an overview of our activities so far, and engage the wider Python community to help us move forward.

Our Goals

When Donald (our lead developer) and I first talked about the project, he had some very clear objectives for the redesign:

To update the visual identity
To make packages more discoverable; and
To look after both kinds of users, namely, users and package maintainers

To this list, I added a two of my own objectives:

First; to give the project the same level of professionalism as a commercial project of the same scale.

Second; to ensure that the user experience reflect the Python community that I know - a community that is welcoming, helpful and inclusive.

What We’ve Done

So now you see our goals, let’s take a look at the solution we’ve come up with so far.

Making the UI Welcoming

Python is used by many community and educational organisations to introduce newcomers to programming. By extension, PyPI might be the first package manager that some of our users have ever seen. This is a big responsibility, but also an opportunity to make a small part of the learning journey easier.

In designing the user interface, I tried to make no assumptions about prior knowledge. Don’t know what pip is? That’s ok - we’ll link you to the appropriate help section. Not sure what to do with an MD5 hash? No worries - there’s a help popover for that.

The colours, fonts, text sizes and spacing were also designed to be large, friendly and accessible (we’ll talk more about accessibility later) - all in an attempt to make new coders comfortable with the tool at hand.

Now - you might be thinking - “but most PyPI users are not beginners, so why design for them?” The answer is simple: a site designed for beginners can be used by everyone; a site designed for experts may alienate and confuse beginners. Of course, getting this right is a challenge, so we’ll be usability testing the design to find a balance that works for users of all experience levels.

Helping Users Overcome Obstacles

To ensure that all of our users are getting the most out of PyPI, it’s not enough just to design an interface - I needed to look at the whole user experience. This meant thinking about an individual’s experience moving through the site, and asking myself:

Where could our users be getting ‘stuck’?
How can I help them on their way?

Not only did this mode of thinking influence a lot of my interface design decisions, it also led me to explore the documentation resources that are currently available.

Currently, the Python Packaging User Guide is the authoritative resource on Python packaging. Unfortunately, it is not linked to from PyPI itself; and while the content is of very high quality, the tutorials are written through the lens of a more experienced Pythonista. I wanted something with a much lower threshold… something that would really hold the user’s hand when they got stuck.

In October I put out a call for help writing two new tutorials to help beginners; one for users who have never installed a package, and one for users who want to upload their first package to PyPI. My hope was that I’d attract a couple of technical writers to the project, but after an incredible response from the Python community (and consulting with Marcus and the PyPA team) we’ve settled on something more ambitious: to edit the current packaging guide to include new tutorials, while improving and extending the documentation in general.

Our goal is to complete this work by early 2016 to coincide with the launch of the new Warehouse codebase. This will facilitate extensive linking between the two resources, and dramatically improve the overall user experience.

Ensuring the Site Is Inclusive

The final piece of the puzzle is ensuring that the site is usable and accessible for all of our community members, whether they are using a phone, screen reader or an old, unpopular browser.

This has resulted in a number of technical decisions; the first (and most obvious) is that the design supports a range of devices via responsive media queries. We’re also going to (at least in the short term) continue support for Internet Explorer 8 9, as we have a number of users, primarily in China, still using this browser. See this issue for more information.

On the accessibility side, the project has already benefited from one audit from Xavier Dutreilh and we are looking forward to another before the site launches. Planned improvements include the addition of ARIA roles to the HTML, a ‘skip to content’ link, as well as better labeling of form fields for screen readers.

Lastly, Donald is introducing both localisation and internationalisation to the codebase. Currently PyPI is very US centric - supporting US English and US formats only. We’re very excited to be updating the user experience to better support Python users from all over the world, and will be calling for volunteers in early 2016 to assist us in this activity.

How You Can Help

So what’s next? And importantly - how can you help?

Contributing Code

We have a huge amount of work to complete before launching Warehouse, and would love to see some new faces working on the project. If you have skills in Python, HTML, SCSS, or JavaScript, then please check out the open issues on the issue tracker. Thanks to Donald’s hard work, the project itself is easy to set up and extensively documented. If you’ve never contributed to an open-source project before, or are new to web development, we’d love to accept your first pull request! We have labelled a number of issues on the issue tracker as ‘easy’ - start here!

Participating in Usability Testing

As already mentioned, I am planning on running a number of usability testing sessions. The objectives of these sessions is to ask:

Are the design decisions really helping new learners?
Have I got the balance right for more experienced Pythonistas?
Is it clear what each page does?
Can users find help when they need it?

Since making a call for volunteers, over 150 Pythonistas have come forward to participate. From these, I will ask a variety of users to participate in the tests - the objective being to test with users from different backgrounds and with different levels of Python experience. If you think that you have a new perspective to bring to this process, please volunteer here.

Helping Rewrite PyPUG

I’m very excited to report that the work on rewriting the Python Packaging User Guide has already begun, with Daniel Beck leading a team of volunteer writers. If you’d like to get involved in this project, please start by visiting this ticket on the issue tracker - Daniel and the team would be excited for your contribution!

Providing Feedback

Finally, we’re planning on installing a widget on the site to gather community feedback. Perhaps there is something small that is bothering you, but it doesn’t justify opening an issue on the issue tracker. Perhaps there is something big, but you don’t like issue trackers, or find them difficult or intimidating to use. Perhaps you just want to put an opinion forward. In all of these cases, please use our widget - we can only better serve the community if we hear from the community!

Wrapping Up

Warehouse is an exciting, interesting and challenging project to work on, and I’m very pleased to have been able to make a large impact on such an important project for the Python community.

There is still lots to do and many challenges ahead, but I am confident that the final site will deliver significant improvements to the user experience for Python users across the globe.

Stay tuned for my next article which will explore the new design in more depth.

Update (27th Feb, 2018)

My intention to write a series of posts on this subject was never realised - so instead, here an update on the project (and this article):

Last year, the PSF’s Packaging Working Group applied for and recived a Mozilla Open Source Support grant to focus on Warehouse (more detail here). I’m amongst the group of developers who can now dedicate paid time to focus on getting the new PyPI up to standard and fully replacing legacy PyPI.
Warehouse is now available to try at the pre-production site.
There has been lots of great work completed on the Python Packaging User Guide - Warehouse is taking full advantage of this by liberally linking to relevant documentation.
Instead of installing a feedback widget on the site, we decided to go with prominent links to open new GitHub issues, at least for now.
There has been a big focus on making it easier to dive into the Warehouse codebase, with several “good first issue” items and an improved “Getting Started” guide. Maintainer Ernest W. Durbin III will even help you with a one-on-one session and give you stickers!
After much discussion we removed localisation and internationalisation functionality from the codebase, but are working on bringing it back in a sustainable way.
You can follow the Warehouse development roadmap or watch our rollout board on GitHub to see as we progress towards launch.

Learning Python, Learning French - My Talk from PyConFr

2015-12-14T00:00:00+00:00

In October 2015, I had the opportunity to present at PyConFr in the beautiful city of Pau. My talk explored my experiences of learning Python and French at the same time and looked at what the Python community could take from the language learning community to better help new learners.

I’d like to thank the organisers of PyConFr for having me - it was a terrific conference, and I was so happy to present my ideas to such a warm and welcoming group of Pythonistas. Thanks also to all those attendees who were patient with my less than perfect French, or happy to switch to English when I got stuck!

The talk is in English, with a brief introduction in French (for which I have provided subtitles). Enjoy!

Or watch on YouTube

And here is a copy of my slides for the curious:

My First DjangoCon

2015-06-15T00:00:00+01:00

DjangoCon Europe was held for a week in Cardiff, Wales. It was my first conference and I was very excited to finally meet a lot of people within the community who I knew via twitter, email and IRC.

Talks

I enjoyed the vast majority of the talks and managed to take something out of almost every one of them. Without a doubt the most memorable talk was a lightning talk by Russell Keith-Magee, where he talked about his feelings of doubt and inadequacy and disclosed that he had been going though a major depressive episode. In his talk, Russell used his own position within the community to urge others to seek help if they need it - including with the Cardiff University wellbeing team who the organisers had arranged to be on hand for three days of the conference. Thank-you Russell, and get well soon :)

On a practical level two other talks stood out to me - Hanna Kollo’s Avoiding monoliths and David Winterbottom’s How to write a view. Both were really talks about application and code structure - topics that I’ve been considering more and more as Connect has grown.

A few other things I learned:

Load testing is not that difficult! If you can unit test you can load test. This was quite a revelation for me as I had always assumed it was some kind of dark art that only the most senior software engineers are qualified to practice. Turns out, it’s not and there are libararies that can help you do it.
Pytest is awesome and I should totally be using it. And (apparently) it’s not at all difficult to make the switch.
Security is hard…

… and web accessibility is important!

Sprints

After speaking to a few people about Connect, I decided to open source the code with the intention of launching a mentoring platform for the Django community.

After sorting out some installation bugs, we ended up with seven people hacking on the code and making general improvements. There’s lots planned and I’m looking forward to leading my first open source project!

Community

Finally, I wanted to make a note on community. I was overwhelmed by the friendliness, generosity and openness of the community. Never once did I feel as though I shouldn’t be there, participating and contributing. To all of the people I met - thank-you! You made my first DjangoCon awesome!

Beginning BDD with Django - Part Two

2015-03-19T00:00:00+00:00

This is the second in a two part series attempting to answer the questions:

Why should I consider using BDD?
What are the key concepts?
How can I use it to test my Django project?

In the first half of this series we outlined the benefits of BDD and scoped and wrote a Gherkin feature file for our Filter Users feature. In this part we’ll use Behave to hook up our feature file to an automated test suite.

This guide has been tested to work with the following stack:

Python 3.3
Django 1.7
Factory Boy 2.4.1
Splinter 0.7.0
Selenium 2.44.0
Django Behave 0.1.2
Phantom JS 1.9.8

Revisiting Our Feature File

For reference, let’s take a quick look at the Filter Users feature we wrote in the first part of this series:

filter_users.feature

Feature: Filter users by interest
As a standard user
I want to filter users by their listed interests
So I can find users who have similar interests to my own

Background: There are interests and users in the system
Given there are a number of interests:
| interest |
| Django |
| Testing |
| Public Speaking |
| DevOps |
| PHP |

    And there are many users, each with different interests:
        |    name           |   interests                  |
        |    Billie Jean    |   Django, Testing            |
        |    Rocky Raccoon  |   Django, Public Speaking    |
        |    Major Tom      |   Testing, Devops            |
        |    Bobbie McGee   |   Public Speaking, DevOps    |

Scenario Outline: Filter users
Given I am a logged in user
When I filter the list of users by <filter>
Then I see <num> users

    Examples:
        |    filter             |    num    |
        |    Django             |    2      |
        |    Django, Testing    |    3      |
        |    PHP                |    0      |

Remember that? Great! Let’s get started.

Dependencies

First off, we’ll need to install our dependencies:

Behave will run our BDD tests.
Django Behave will let us run our Behave tests via the Django test runner.
PhantomJS will drive our interactions with the browser.
Splinter sits on top of PhantomJS (and others) and will help us write simpler, more elegant test code.
Factory Boy will allow us to generate Users and Interests to use in our tests.

After installing all of the above, update settings.py:

Add django-behave to INSTALLED_APPS
Set TEST_RUNNER = 'django_behave.runner.DjangoBehaveTestSuiteRunner'

Note

We'll be using Django's built in test runner throughout this tutorial. But if you prefer to use PyTest, then you should check out pytest-django and pytest-bdd.

Folder Structure

Next we’ll need to create a new bdd app where we can save our existing feature file as filter_users.feature:

project_root/
bdd/
init.py
features/
filter_users.feature
environment.py
steps/
filter_users.py

Note

We could instead include feature folders inside individual existing Django applications. However, utilising one central bdd application allows us to share the same environment for all of our tests, whilst accounting for situations where individual tests cases span multiple Django applications.

Remember to add bdd to your INSTALLED_APPS in your settings.py file.

Setting Up Our Test Environment

Creating Factories

Because we’ve already written our feature file, we know that we’ll need Users and Interests in the database to run our test scenarios. To create these, we’ll use Factory Boy - a features replacement tool.

We’ll setup our factories in the same application that our User and Interest models are defined:

project_root/
accounts/
models.py # Our User and Interest models live here
factories.py # This is where we'll create our Factory Boy factories

factories.py

import factory
from django.contrib.auth.hashers import make_password
from .models import Interest, User

class UserFactory(factory.django.DjangoModelFactory):
"""
Creates a standard active user.
"""
class Meta:
model = User

    first_name = 'Standard'
    last_name = 'User'
    # Emails must be unique - so use a sequence here:
    email = factory.Sequence(lambda n: 'user.{}@test.test'.format(n))
    password = make_password('pass')
    is_active = True

    @factory.post_generation
    def interests(self, create, extracted, **kwargs):
        """
        Where 'interests' are defined, add them to this user.
        """
        if not create:
            return

        if extracted:
            for interest in extracted:
                self.interest.add(interest)

class InterestFactory(factory.django.DjangoModelFactory):
class Meta:
model = Interest

    name = factory.Sequence(lambda n: 'interest{}'.format(n))

Let’s go over whats going on here:

First, we define the model we want to instantiate by setting the model inside the class Meta block.

Next, we define defaults for the corresponding model fields. In our example, all of our users will have the first name of ‘Standard’ unless we specify otherwise.

For the email field (in our UserFactory) and name field (in our InterestFactory), we can use a factory sequence, so that each object in our factory is unique. If we now create two instances of InterestFactory, they will each have a unique name - the first will be interest1, the second interest2.

Finally, to define the many-to-many relationship between User and Interest, we need to setup our interests as a method using the post_generation hook.

Voila! Now we’re all set to create objects in our tests. For example, we can:

# Create a User with the default settings

user = UserFactory() # Will generate a user with the name 'Standard User'

# Create a User with a custom name

major_tom = UserFactory(first_name='Major', last_name='Tom')

# Create a User with Interests

django = InterestFactory(name='Django')
public_speaking = InterestFactory(name='Public Speaking')
lucy_diamond = UserFactory(first_name='Lucy', last_name='Diamond',
interests=(django, public_speaking))

Configuring environment.py

We can use our environment.py file to define what should happen before and after certain points in our tests. There are several hooks we can utilise, but for our example, we’re going to focus on:

before_all Code defined here will run before all of our tests begin. We’ll use this hook to set up our browser.
after_all Code defined here will run after all of our tests finish. We’ll use this hook to quit our browser.
before_scenario Code defined here runs before each individual scenario. We’ll use this to setup (and teardown) our database. This will help us keep our data clean between each scenario.

Our example:

environment.py

from behave import *
from splinter.browser import Browser
from django.core import management

def before_all(context): # Unless we tell our test runner otherwise, set our default browser to PhantomJS
if context.config.browser:
context.browser = Browser(context.config.browser)
else:
context.browser = Browser('phantomjs')

    # When we're running with PhantomJS we need to specify the window size.
    # This is a workaround for an issue where PhantomJS cannot find elements
    # by text - see: https://github.com/angular/protractor/issues/585
    if context.browser.driver_name == 'PhantomJS':
        context.browser.driver.set_window_size(1280, 1024)

def before_scenario(context, scenario): # Reset the database before each scenario # This means we can create, delete and edit objects within an # individual scenerio without these changes affecting our # other scenarios
management.call_command('flush', verbosity=0, interactive=False)

    # At this stage we can (optionally) generate additional data to setup in the database.
    # For example, if we know that all of our tests require a 'SiteConfig' object,
    # we could create it here.

def after_all(context): # Quit our browser once we're done!
context.browser.quit()
context.browser = None

The context variable is an instance of behave.runner.Context. This variable holds additional contextual information during the running of tests, so we could also pass it additional information and retreive that value later.

Running Our Tests

Now, we’ve setup our environment, we’re ready to run our tests! In your terminal run:

python manage.py test bdd

You’ll see:

Failing scenarios:
bdd/features/filter_users.feature:22 Filter users
bdd/features/filter_users.feature:22 Filter users
bdd/features/filter_users.feature:22 Filter users

0 features passed, 1 failed, 0 skipped
0 scenarios passed, 3 failed, 0 skipped
0 steps passed, 0 failed, 0 skipped, 15 undefined
Took 0m0.000s

Why? Because Behave can’t find any instructions (known as steps) for each of our scenarios. Conveniently, Behave provides us with some default snippets. Copy these from your terminal and paste them into the filter_users.py file - grouping common steps together:

from behave import \* # We'll need to import all from behave first

# Then we can copy the snippets into our file

@given('there are a number of interests')
def impl(context):
assert False

@given('there are many users, each with different interests')
def impl(context):
assert False

@given('I am a logged in user')
def impl(context):
assert False

@when('I filter the list of users by Django')
def impl(context):
assert False

@when('I filter the list of users by Django, Testing')
def impl(context):
assert False

@when('I filter the list of users by PHP')
def impl(context):
assert False

@then('I see 3 users')
def impl(context):
assert False

@then('I see 2 users')
def impl(context):
assert False

@then('I see 0 users')
def impl(context):
assert False

Step functions are defined using step decorators, here shown as @given, @then and @when. These are universally imported when you import Behave; you do not need to import them individually.

Step decorators use a string to match your Gherkin feature file step - this must be an exact match for the test to run correctly.

The decorated function (in this case def impl()) can be named anything - It doesn’t matter. The only thing you must do is pass it the context that we mentioned earlier.

Writing Test Code

Let’s go through each of our steps and write our test code.

1. Given there are a number of interests

For this step, we’ll need to use our InterestFactory to create the interests listed in our feature file. We can access the name of our interests by looping over each row in our context.table using the interest column heading as a key.

filter_users.py

from behave import *
from accounts.factories import InterestFactory

@given('there are a number of interests')
def impl(context):
interests = [InterestFactory(name=row['interest']) for row in context.table]

2. And there are many users, each with different interests

In this step we create our users by:

Splitting the items listed under our ‘interest’ heading into list items
Fetching the interests (that we created in our last step) from the database
Creating a new user with our UserFactory, passing in the the interest objects

filter_users.py

from accounts.factories import UserFactory
from accounts.models import Interest

@given('there are many users, each with different interests')
def impl(context):
for row in context.table:
interest_names = row['interests'].split(', ')
interests = Interest.objects.filter(name\_\_in=interest_names)
UserFactory(email=row['email'], interests=interests)

3. Given I am a logged in user

To log in a user, we navigate to the login page and interact with the login form. Here we can start to appreciate the power of Splinter for browsing, finding and filling in form fields.

filter_users.py

from accounts.factories import UserFactory

@given('I am a logged in user')
def impl(context): # First we need to create the user to login.
user_to_login = UserFactory(email='log.me.in@test.test') # All properties (other than email) will be inherited from our UserFactory. # Therefore our password for this user will be 'pass'.

    # We visit the login page
    # context.config.server_url is by default set to http://localhost:8081
    # (Thanks to Cynthia Kiser for pointing this out.)
    # In this example we're visiting http://localhost:8081/accounts/login/
    context.browser.visit(context.config.server_url + 'accounts/login/')

    # Next, we log in our user by interacting with the login form
    # Splinter has a handy fill function that helps us fill form fields based
    # on their name.  We'll use it to fill in the username and password fields.
    context.browser.fill('username', user_to_login.email)
    context.browser.fill('password', 'pass')

    # Finally we find the submit button (by its CSS attribute) and click on it!
    context.browser.find_by_css('form input[type=submit]').first.click()

At this point it might be helpful to see our tests running in a ‘real’ browser. To do this, we need to install Selenium.

Now we can tell Splinter to run our tests using Firefox (rather than the default PhantomJS):

$ python ./manage.py test bdd --behave_browser firefox

Note

Running with Firefox is significantly slower than with PhantomJS, so unless I'm debugging, I tend to stick with running PhantomJS locally and test with other, heavier browsers on my continuous integration server.

4. When I filter the list of users by …

We can combine each of our filter steps into one single step by using Behave’s step parameters.

First, we need to change our feature file, wrapping our filter variable in string formatting:

filter_users.feature

Scenario Outline: Filter users
    ...
    When I filter the list of users by "<filter>"
    ...

This allows us to write one (and only one) step for each filter step:

filter_users.py

@when('I filter the list of users by "{checked}"')
def impl(context, checked):

    # First we visit the page where we see all the users.
    # In our example, this happens to be the root domain.
    context.browser.visit(context.context.config.server_url)

    # Then we get the list of interests
    checked = checked.split(', ');
    for check in checked:
        # And click on each label.
        # This code assumes we have a form where each interest is listed as a
        # label containing a checkbox.
        path = "//label[contains(.,'{}')]/input".format(check)
        context.browser.find_by_xpath(path).click()

    # Finally, we submit the form
    context.browser.find_by_css('form input[type=submit]').first.click()

5. Then I see … users

Finally, we can use the same pattern to count the number of users in our results.

filter_users.feature

Scenario Outline: Filter users
    ...
    ...
    Then I see "<num>" users

And in our python file:

filter_users.py

@then('I see "{count}" users')
def impl(context, count):
    # Assuming there is a <div class="user-card"></div> for each user
    users = context.browser.find_by_css('.user-card')

    # We can now assert that the number of users on the page
    # is equal to the number we expect
    assert len(users) == int(count)

Wrapping Up

That’s it for our test code! Now it’s over to you to write application code to make these failing scenarios pass.

I hope you’ve enjoyed reading these articles as much as I’ve enjoyed writing them. If you have any questions or comments, don’t hesitate to leave them below.

Beginning BDD with Django - Part One

2015-03-16T00:00:00+00:00

For the last year I’ve been learning Django by building Connect. Part of this journey has been to explore various automated testing methods and tools. Behaviour Driven Development (BDD) is one technique that really spoke to me and was surprisingly simple to integrate into my application.

This article is the first of two parts that aim to pass on what I have learnt so far. It is not an in-depth exploration of the philosophy or best-practice application of BDD, but rather a highly practical example to get you started.

By the end of both articles, I hope you will be able to answer the following questions:

Why should I consider using BDD?
What are the key concepts?
How can I use it to test my app?

Let’s do it!

Why BDD

I’m not going to go into why you should test your application. I assume that by reading this article you’re already sold on the benefits of testing. Instead I’m going to focus on why you should specifically consider BDD for your next app.

To do this, we need to step back and ask ourselves why are we building software in the first place and how we can assess the success of our application.

In a great talk titled building the minimum badass user, Kathy Sierra argues that a successful application is one that people want to use and tell their friends about. The key to delivering this? Making our user awesome:

“People aren’t using the app because they like the app or they like you. They’re doing it because they like themselves.”

Kathy argues that users will endure less than perfect design, or technical implementation if the app makes them more awesome at the task at hand.

For developers, the key take-away is that we need to be constantly thinking about how we can empower our users.

How BDD Can Help

BDD sits at the cusp of user experience and development, as it forces us to frame the software we’re developing in the context of the user.

It helps us step back from the technical implementation and focus on these questions:

Who am I?
What can I do?
What benefits can I derive from my action?

A common template for defining this is:

As a <role>
I want <feature>
So that <value>

This template also accounts for scenarios where the role is not a user, but rather a system or process (for example, an API).

An Example

To illustrate how we can transition from user-centered design thinking to writing test code and developing our application, we’re going to walk through an example from Connect; a social application that helps users connect with each other based on common interests and location.

Let’s imagine that we’ve built most of the app, but are yet to develop one of the most important features: filtering users by interests.

Using the pattern defined earlier, we might describe this feature as:

As a standard user
I want to filter users by their listed interests
So I can find users who have similar interests to my own

Feature Files

BDD can be segmented into two parts: the feature file, where we describe the behaviour we are going to build, and the code (in our case Python) where we test our application.

First we’ll need to write our feature file. Feature files use the Gherkin syntax and are saved as <featurename>.feature:

example.feature

Feature: feature name
  description
  further description

Background: some requirement of this test
Given some setup condition
And some other setup action

Scenario: some scenario
Given some condition
When some action is taken
Then some result is expected

Lines 1-3: Defining the Feature

Technically, only the feature name is required here. However, I also like to describe the feature using the As a, I want, So that pattern established earlier. This keeps our user’s needs front of mind.

Lines 5-7: Setting Up the Background

A feature’s Background outlines the contextual information we need for the scenarios that follow. For our example, we’re going to need Interests and Users in the database so we can filter our users.

Not all features will require a background, so this section is entirely optional.

Lines 9-12: Writing Scenarios

Finally, we outline the different scenarios our users might face.

For our example, we need to consider what will happen when the user filters by one, or multiple interests. We also need to account for when there are no users that match the request.

Each Scenario contains three types of steps:

Given: Defines the state of the system
When: Defines the action the user or system wants to take
Then: Defines the outcome of the action

More complex scenarios can also include And or But keywords. For example:

activate_account.feature

Scenario: Activate account
    Given I am a standard user
    But I have not yet activated my account
    When I visit my account activation page
    And I fill out the form
    But I forget to confirm my password
    And I submit the form
    Then I see an error

Putting It All Together

Here’s our filter users feature written as a Gherkin feature file:

filter_users.feature

Feature: Filter users by interest
As a standard user
I want to filter users by their listed interests
So that I can find users who share my interests

Background: There are interests and users in the system
Given there are a number of interests in the database
And there are many users in the database, each with different interests

Scenario: Filter users by one interest
Given I am a logged in user
When I filter the list of users by a single interest
Then I only see the users with that interest

Scenario: Filter users by multiple interests
Given I am a logged in user
When I filter the list of users by multiple interests
Then I see the users with those interests

Scenario: No result
Given I am a logged in user
When I filter the list of users by an interest that no-one has listed
Then I see no users

Refactoring

You’ve probably noticed that our scenarios use a common pattern. They’re also a little vague. To fix this we can include more context in our Background and refactor our three scenarios into one Scenario Outline:

filter_users.feature

Feature: Filter users by interest
As a standard user
I want to filter users by their listed interests
So I can find users who have similar interests to my own

Background: There are interests and users in the system
Given there are a number of interests:
| interest |
| Django |
| Testing |
| Public Speaking |
| DevOps |
| PHP |

    And there are many users, each with different interests:
        |    name           |   interests                  |
        |    Billie Jean    |   Django, Testing            |
        |    Rocky Raccoon  |   Django, Public Speaking    |
        |    Major Tom      |   Testing, Devops            |
        |    Bobbie McGee   |   Public Speaking, DevOps    |

Scenario Outline: Filter users
Given I am a logged in user
When I filter the list of users by <filter>
Then I see <num> users

    Examples:
        |    filter             |    num    |
        |    Django             |    2      |
        |    Django, Testing    |    3      |
        |    PHP                |    0      |

First we define the interests and users in the background using tables. This makes our data easy to read, whilst providing hooks that we’ll use later in our Python code.

Next, we compile our scenarios into one Scenario Outline, specifying the skills and number of users based on the information defined in our new Background. When we run our tests, a Scenario will be created out of each (non heading) line in the example table. So, the first line would become…

Given I am a logged in user
When I filter the list of users by Django
Then I see 2 users

… and so on.

Conclusion

That’s it! We’ve defined our feature and written our feature file!

In the next post we’ll explore how we can write Python code to utilise our feature file and run it as an automated test.

Tutorial : Implementing Django Formsets

2015-01-06T00:00:00+00:00

I’ve noticed on #django IRC that many people need guidance on formsets, and as I’ve now used them in a couple of my projects — most recently, Connect — I thought I could offer a short how-to based on my own experiences.

Firstly, if you haven’t already, go and read the docs. If you’re still confused, or want an end-to-end tutorial, then read on. The code contained in this tutorial has been tested to work with Django 1.7.

What Does a Formset Do?

Formsets are for dealing with sets of identical data. For example in Connect, I have a form where the user can save multiple links to their public profile, with each link having both a URL and an anchor:

A Django formset in action.

I also want:

The formset to be nested within the user’s profile form.
The user to add or remove as many links as they like.
Custom validation checking that no anchor or URL is entered more than once.

Django comes with a number of ‘batteries included’ formsets. There are formsets for models and formsets for models related by a foreign key.

This how-to, however, is going to focus on creating a standard formset using custom forms.

Step 1. Create Your Forms

First we need to set out our link form. This is just a standard Django form.

forms.py

from django import forms

class LinkForm(forms.Form):
"""
Form for individual user links
"""
anchor = forms.CharField(
max_length=100,
widget=forms.TextInput(attrs={
'placeholder': 'Link Name / Anchor Text',
}),
required=False)
url = forms.URLField(
widget=forms.URLInput(attrs={
'placeholder': 'URL',
}),
required=False)

As our formset will need to be nested inside a profile form, let’s go ahead and create that now:

forms.py

class ProfileForm(forms.Form):
    """
    Form for user to update their own profile details
    (excluding links which are handled by a separate formset)
    """
    def __init__(self, *args, **kwargs):
        self.user = kwargs.pop('user', None)
        super(ProfileForm, self).__init__(*args, **kwargs)

        self.fields['first_name'] = forms.CharField(
                                        max_length=30,
                                        initial = self.user.first_name,
                                        widget=forms.TextInput(attrs={
                                            'placeholder': 'First Name',
                                        }))
        self.fields['last_name'] = forms.CharField(
                                        max_length=30,
                                        initial = self.user.last_name,
                                        widget=forms.TextInput(attrs={
                                            'placeholder': 'Last Name',
                                        }))

Step 2. Create Your Formset

For this particular example, we’re going to add some validation to our formset, as we want to ensure that there are no duplicate URLs or anchors.

We also want to verify that all links have both an anchor and URL. We could simply set the fields as required on the form itself, however this will prevent our users from submitting empty forms, which is not the behaviour we’re looking for here. From a usability perspective, it would be better to simply ignore forms that are completely empty, raising errors only if a form is partially incomplete.

If you don’t want any custom validation on your formset, you can skip this step entirely.

forms.py

from django.forms.formsets import BaseFormSet

class BaseLinkFormSet(BaseFormSet):
def clean(self):
"""
Adds validation to check that no two links have the same anchor or URL
and that all links have both an anchor and URL.
"""
if any(self.errors):
return

        anchors = []
        urls = []
        duplicates = False

        for form in self.forms:
            if form.cleaned_data:
                anchor = form.cleaned_data['anchor']
                url = form.cleaned_data['url']

                # Check that no two links have the same anchor or URL
                if anchor and url:
                    if anchor in anchors:
                        duplicates = True
                    anchors.append(anchor)

                    if url in urls:
                        duplicates = True
                    urls.append(url)

                if duplicates:
                    raise forms.ValidationError(
                        'Links must have unique anchors and URLs.',
                        code='duplicate_links'
                    )

                # Check that all links have both an anchor and URL
                if url and not anchor:
                    raise forms.ValidationError(
                        'All links must have an anchor.',
                        code='missing_anchor'
                    )
                elif anchor and not url:
                    raise forms.ValidationError(
                        'All links must have a URL.',
                        code='missing_URL'
                    )

Step 3. Hook Up Your View

Now we can use Django’s built in formset_factory to generate our formset. As the name suggests, this function takes a form and returns a formset. At its most basic, we only need to pass it the form we want to repeat - in this case our LinkForm. However, as we have created a custom BaseLinkFormSet, we also need to tell our factory to use this instead of using Django’s default BaseFormSet.

In our example, we also want our formset to display all of the existing UserLinks for the logged in user. To do this, we need to build a dict of our user’s links and pass this as our initial_data.

To save our data we can build a list of UserLinks and save this to the user’s profile using the bulk_create method. Wrapping this code in a transaction will avoid a situation where the old links are deleted, but the connection to the database is lost before the new links are created.

We are also going to use the messages framework to tell our users whether their profile was updated.

views.py

from django.contrib import messages
from django.contrib.auth.decorators import login_required
from django.core.urlresolvers import reverse
from django.db import IntegrityError, transaction
from django.forms.formsets import formset_factory
from django.shortcuts import redirect, render
from myapp.forms import LinkForm, BaseLinkFormSet, ProfileForm
from myapp.models import UserLink

@login_required
def test_profile_settings(request):
"""
Allows a user to update their own profile.
"""
user = request.user

    # Create the formset, specifying the form and formset we want to use.
    LinkFormSet = formset_factory(LinkForm, formset=BaseLinkFormSet)

    # Get our existing link data for this user.  This is used as initial data.
    user_links = UserLink.objects.filter(user=user).order_by('anchor')
    link_data = [{'anchor': l.anchor, 'url': l.url}
                    for l in user_links]

    if request.method == 'POST':
        profile_form = ProfileForm(request.POST, user=user)
        link_formset = LinkFormSet(request.POST)

        if profile_form.is_valid() and link_formset.is_valid():
            # Save user info
            user.first_name = profile_form.cleaned_data.get('first_name')
            user.last_name = profile_form.cleaned_data.get('last_name')
            user.save()

            # Now save the data for each form in the formset
            new_links = []

            for link_form in link_formset:
                anchor = link_form.cleaned_data.get('anchor')
                url = link_form.cleaned_data.get('url')

                if anchor and url:
                    new_links.append(UserLink(user=user, anchor=anchor, url=url))

            try:
                with transaction.atomic():
                    #Replace the old with the new
                    UserLink.objects.filter(user=user).delete()
                    UserLink.objects.bulk_create(new_links)

                    # And notify our users that it worked
                    messages.success(request, 'You have updated your profile.')

            except IntegrityError: #If the transaction failed
                messages.error(request, 'There was an error saving your profile.')
                return redirect(reverse('profile-settings'))

    else:
        profile_form = ProfileForm(user=user)
        link_formset = LinkFormSet(initial=link_data)

    context = {
        'profile_form': profile_form,
        'link_formset': link_formset,
    }

    return render(request, 'our_template.html', context)

Step 4. HTML / JS

Now that we have passed our formset to our template, we can use a forloop to display each of our forms.

An additional (but not necessarily obvious) step here is to include {{ link_formset.management_form }}. This is used by Django to manage the forms within the formset.

My personal preference is to individually specify each form field so I can wrap additional HTML around it, but you can also use the standard shortcuts, such as {{ form.as_p }} within a formset.

We also want to use this jQuery plugin for dynamically adding and removing forms. Full documentation can be found here.

edit_profile.html

{% load staticfiles %}

{% if messages %}
{% for message in messages %}
<p>{{ message }}</p>
{% endfor %}
{% endif %}

<form method="post">
    {% csrf_token %}

    <label>First Name</label>
    {{ profile_form.first_name }}
    {% if profile_form.first_name.errors %}
        {% for error in profile_form.first_name.errors %}
            {{ error|escape }}
        {% endfor %}
    {% endif %}

    <label>Last Name</label>
    {{ profile_form.last_name }}
    {% if profile_form.last_name.errors %}
        {% for error in profile_form.last_name.errors %}
            {{ error|escape }}
        {% endfor %}
    {% endif %}

    {{ link_formset.management_form }}

    {% for link_form in link_formset %}
        <div class="link-formset">
            {{ link_form.anchor }}
            {% if link_form.anchor.errors %}
                {% for error in link_form.anchor.errors %}
                    {{ error|escape }}
                {% endfor %}
            {% endif %}

            {{ link_form.url }}
            {% if link_form.url.errors %}
                {% for error in link_form.url.errors %}
                    {{ error|escape }}
                {% endfor %}
            {% endif %}
        </div>
    {% endfor %}

    {% if link_formset.non_form_errors %}
        {% for error in link_formset.non_form_errors %}
            {{ error|escape }}
        {% endfor %}
    {% endif %}

    <input type="submit" value="Update Profile" class="button"/>

</form>

<!-- Include formset plugin - including jQuery dependency -->
<script src="//ajax.googleapis.com/ajax/libs/jquery/2.1.3/jquery.min.js"></script>
<script src="{% static 'path_to/jquery.formset.js' %}"></script>
<script>
    $('.link-formset').formset({
        addText: 'add link',
        deleteText: 'remove'
    });
</script>

Unit Testing

Let’s set up some basic unit tests to make sure everything is working correctly.

As the profile form is available only to authenticated users, we’ll use the setup method to create and login a user. In the examples below I’ve used factory boy to generate a dummy user.

Most of the examples below are variations on posting the same data either to the view or the form directly. For this reason, much of this functionality has been split into separate helper functions.

Test the Profile Form

We can test the ProfileForm by passing data variations to the object and checking for validation errors.

tests/test_forms.py

from django.test import TestCase
from myapp.factories import UserFactory
from myapp.forms import ProfileForm

class ProfileFormTest(TestCase):
def setUp(self):
self.user = UserFactory()
self.client.login(username=self.user.email, password='pass')

    def form_data(self, first, last):
        return ProfileForm(
            user=self.user,
            data={
                'first_name': first,
                'last_name': last,
            }
        )

    def test_valid_data(self):
        form = self.form_data('First', 'Last')
        self.assertTrue(form.is_valid())

    def test_missing_first_name(self):
        form = self.form_data('', 'Last')
        errors = form['first_name'].errors.as_data()
        self.assertEqual(len(errors), 1)
        self.assertEqual(errors[0].code, 'required')

    def test_missing_last_name(self):
        form = self.form_data('First', '')
        errors = form['last_name'].errors.as_data()

        self.assertEqual(len(errors), 1)
        self.assertEqual(errors[0].code, 'required')

Test the Formset

We can test our formset by either:

Passing data to the ProfileForm (for this to work we must include the TOTAL_FORMS and INITIAL_FORMS settings that are generated by the management_form).
Posting data directly to the view. This allows us to check for specific errors using assertFormsetError.

tests/test_forms.py

from django.core.urlresolvers import reverse
from django.test import TestCase
from myapp.factories import UserFactory
from myapp.forms import ProfileForm

class LinkFormsetTest(TestCase):
def setUp(self):
self.user = UserFactory()
self.client.login(username=self.user.email, password='pass')

    def form_data(self, anchor, url):
        return ProfileForm(
            user=self.user,
            data={
                'first_name': 'First',
                'last_name': 'Last',
                'form-TOTAL_FORMS': 1,
                'form-INITIAL_FORMS': 0,
                'form-0-anchor': anchor,
                'form-0-url': url,
            }
        )

    def post_data(self, anchor1, url1, anchor2='', url2=''):
        return self.client.post(
            reverse('test:profile-settings'),
            data={
                'form-TOTAL_FORMS': 2,
                'form-INITIAL_FORMS': 0,
                'form-0-anchor': anchor1,
                'form-0-url': url1,
                'form-1-anchor': anchor2,
                'form-1-url': url2,
            }
        )

    def raise_formset_error(self, response,error):
        self.assertFormsetError(
            response,
            formset='link_formset',
            form_index=None,
            field=None,
            errors=error
        )

    def test_valid_data(self):
        form = self.form_data('My Link', 'http://mylink.com')
        self.assertTrue(form.is_valid())

    def test_empty_fields(self):
        """
        Test validation passes when no data is provided
        (data is not required).
        """
        form = self.form_data('', '')
        self.assertTrue(form.is_valid())

    def test_duplicate_anchors(self):
        """
        Test validation fails when an anchor is submitted more than once.
        """
        response = self.post_data('My Link', 'http://mylink.com',
                                  'My Link', 'http://mylink2.com')

        self.raise_formset_error(response,
                                 'Links must have unique anchors and URLs.')

    def test_duplicate_url(self):
        """
        Test validation fails when a URL is submitted more than once.
        """
        response = self.post_data('My Link', 'http://mylink.com',
                                  'My Link2', 'http://mylink.com')

        self.raise_formset_error(response,
                                 'Links must have unique anchors and URLs.')

    def test_anchor_without_url(self):
        """
        Test validation fails when a link is submitted without a URL.
        """
        response = self.post_data('My Link', '')

        self.raise_formset_error(response, 'All links must have a URL.')

    def test_url_without_anchor(self):
        """
        Test validation fails when a link is submitted without an anchor.
        """
        response = self.post_data('', 'http://mylink.com')

        self.raise_formset_error(response, 'All links must have an anchor.')

Testing Our View

Finally, we need to check that when we do submit valid data, that data is saved to our user’s profile.

tests/test_views.py

from django.core.urlresolvers import reverse
from django.test import TestCase
from myapp.factories import UserFactory
from myapp.models import User, UserLink

class ProfileSettingsTest(TestCase):
def test_can_update_profile(self):
user = UserFactory()
self.client.login(username=user.email, password='pass')
response = self.client.post(
reverse('test:profile-settings'),
data={
'first_name': 'New First Name',
'last_name': 'New Last Name',
'form-TOTAL_FORMS': 1,
'form-INITIAL_FORMS': 0,
'form-0-anchor': 'My Link',
'form-0-url': 'http://mylink.com',
},
)

        # Get the user again
        user = User.objects.get(id=user.id)
        user_link = UserLink.objects.get(user=user)

        self.assertEqual(user.first_name, 'New First Name')
        self.assertEqual(user.last_name, 'New Last Name')
        self.assertEqual(user_link.anchor, 'My Link')
        self.assertEqual(user_link.url, 'http://mylink.com/')

Conclusion

That’s it! We have a working tested formset saving our user’s links. If you found this article useful, please share it. If you have a comment or question, please get in touch!

2014: My Year of Python

2014-12-29T00:00:00+00:00

At the end of 2013 (and after much convincing from ojh), I decided to make 2014 my ‘year of Python’. I chose a year because I felt that would be enough time to get involved to see if I liked the work and the community - and make a decision as to whether Python (and web development in general) is for me.

Here’s what I did, what I’ve learnt and where I’m going:

Community

PyLadies

I was disappointed that there wasn’t an active Pyladies Australia - so (with some encouragement from the Pyladies mothership) I decided to form one myself. I set up a website and mailing list to which 30+ women have registered, which is a great starting point. I had hoped that I would find a whole heap of other women interested in helping out (running workshops, etc.), but people are busy (!) so at this stage things are fairly dormant. Being in Bendigo, I can’t personally run local workshops (I just don’t think there would be any interest here), so that’s been a bit of a sticking point. Circumstances also meant that I couldn’t attend PyCon Australia, which was a missed opportunity to meet people and get stuff happening.

At this stage I feel that the only way PyLadies Australia is going to move forward is if I put in a huge amount of personal time and energy - something I have to weigh up the benefits of.

Pycon Australia

This year I also volunteered to design the PyCon Australia 2014 logo and website. This was to be my first significant contribution what I thought would be an open-source project - though, unfortunately, the software the site is built upon is private.

What Worked

The process of putting together the logo was fairly straightforward as I had total creative freedom in this respect. The website itself was first designed in HTML, CSS & JS and then integrated into the CMS - a system that worked really well.

What I’d Do Differently

In the end the branding was a bit all-over-the-place, as I didn’t have oversight on all visual materials. It would have been nice to have a list of all of the places the logo would be used to make sure everything was visually coherant. For example the logo on the slide templates really should have sat on a white background.

New pages to the website were published without being checked first, which sometimes meant we had non-responsive elements thrown into the page content. Some kind of design-review-before-publish mechanism may have been helpful.

I would have also liked some more time to put together a better layout for the conference schedule as this didn’t work on mobile at all.

Finally, as mentioned earlier, personal circumstances meant that I didn’t actually get to attend PyCon, which was a real let down - next time I’d definitely like to be there!

Overall, I’d say that my interactions with the Python community have been positive and I am keen to continue to meet people and share my skills.

Code

My main project for the year was Connect - a web application written in Django that helps people connect with each other based on interests and location.

My inspiration for the project was PyLadies Australia - as the women who expressed an interest in participating were located all across the country. Quickly though, I realised that Connect could be used internationally and for a number of different community groups and organisations.

On a professional front, our business also completed two projects for BPCLEtool, for which I was able to contribute small amounts of Python code.

Working with Django has been an absolute delight and I am really starting to appreciate the ‘Pythonic’ way of doing things. Having a community consensus on what constitutes good code is immensely helpful. Much of the syntax seems naturally logical and I like the way that Django encourages modular, structured code.

Learning How I Learn

I am well aware that learning Python via Django is a bad idea - but I’ve learnt that coding exercises like Katas don’t really do it for me. Fundamentally, my reason for learning Python is not to just learn Python - it’s to build stuff! For myself, or for other people.

I think I’ve always known this, but this year has really put that into focus for me. I learn best by trying things - breaking things - then fixing things. On several occasions I tried really hard to do tutorials, read books, or follow videos - but unless they were really engaging, well written (I’m looking at you official Django tutorial), or REALLY pertinent to the issue at hand, I often petered out. Fundamentally, my motivation wanes if I don’t have some kind of creative input into what I’m doing. Also - I like problem solving. I like searching for the answers. And I like reading about different perspectives on the same problem.

So, in searching for answers, here are some of the resources I’ve found most valuable:

The Official Django Tutorial

This seems pretty obvious, right? Apparently not. The number of people on IRC asking basic questions in #django without having done the official tutorial is pretty surprising. I suppose that might be because other frameworks and resources are not nearly as well documented as Django. I think the tutorial is great - it finds a good balance between not too complex and not too simple. Also - (unlike many other tutorials) I found once I had finished, I could actually go and BUILD something. In fact, when I was first starting out, I’d often refer to the tutorial instead of the docs, because I knew where the information I was looking for was located.

Test-Driven Development with Python

Even though I’ve found that tutorial-books aren’t my ideal learning tool, there is enough helpful content here to make following along worthwhile. There are lots of code examples (which I love) and the author does a really good job of selling the benefits of TDD.

Two Scoops of Django

We’ve had this floating around the house for a while and though it was a bit much to take in when I first started, it is a great resource to come back to. I’m quite keen to get into good habits, so am constantly trying to learn about best-practices. It’s hard to find this kind of information online (because everybody has their own opinion), so it’s nice to have it bundled up and presented from well respected members of the Django community.

Secrets of the Testing Masters

The first half of this talk was a real revelation for me - as I was stuck on how to test Connect without getting lost in fixtures. Hello FactoryBoy! :D

This is just my favourite of many videos I have watched on pyvideo which is an AMAZING resource.

The Future

I’m certainly keen to keep learning and engaging with the Python community. I’d like to see more mentoring going on, which I hope Connect can help with. Personally, I’d like to offer my skills and knowledge to help others - not only because I feel this is a great way of giving back, but also because this will help me to cement my knowledge.

On a technical front, I’m currently exploring all manners of techniques and strategies for testing - at the moment that means BDD with behave. I’m excited and optimistic about my future with Python.

You Are Not Your Code

2014-12-18T00:00:00+00:00

Programming is hard. And learning to program is even harder.

And it seems to me that the more experienced you become, the harder the problems get.

Since I started to learn to program, I’ve found it hard to separate professional successes and failures from my own self worth. When something goes right I feel fabulous. When I get stuck on something for days or weeks (hello timezones), then I begin to question whether or not I am ‘cut out’ for it, or if I’m really ‘smart’ enough.

The Myth of the ‘Rockstar’ Developer

Sometimes it’s easy to assume that there is an elite group of developers - the job ads call them rockstars or ninjas - that have been coding since birth. They’ve mastered 15 languages and can code in in their sleep.

But the more I read about this - the more I’ve realised this is a myth. Geniuses are few and far between and most successful people get to where they are with a combination of hard work and a lot of good luck.

Redefining Success - A Reminder to Myself

Comparing yourself to this myth is damaging. Demanding perfection in your code is even worse. Learning to be a great software developer is a journey and there are many things you can bring to the table that don’t require being a ‘rockstar’:

Your Attitude

If you are truly enthusiastic about being the best you can be, you’re already half way there. Curiosity, professionalism, courtesy, honesty, and integrity are essential.

Your ‘Soft Skills’

I really dislike this phrase. What’s ‘soft’ about being able to communicate your ideas effectively? What’s ‘soft’ about being able to resolve conflict? What’s ‘soft’ about being a great leader? As technology and projects change, chances are your soft skills will continue to be of value.

Your Capacity (and Flexibility) to Learn New Things

Technologies change. Requirements change. You are going to face many, many problems that you have little to no idea how to solve. Having a ‘can do’ attitude is essential. So is the humility to know that you don’t have the best answer but are willing to look for it.

Your Delivery

Have you delivered something that is important to yourself, others, society? This is infinitely more valuable than perfection in your code or anything else.

That’s not to say you shouldn’t strive to be a professional. To deliver clean, maintainable code. You should. But remember that you are not your code. You are so much more.

On Creativity

2014-11-18T00:00:00+00:00

I have always considered myself to be creative. One of my earliest memories was drawing in my family lounge room at a child-size portable desk - it was bright yellow and had compartments on the side where I kept my pencils, crayons and textas.

My parents encouraged my creativity - I always had supplies and tried lots of things - sewing, cooking, cake decorating, painting, beading, pottery, paper making. I likened myself to my Grandma or Aunty Julie who between them taught me that being creative was fun and fulfilling.

STEM != Creativity

At school we had one lesson on HTML in IT. Other lessons focused on touch typing, Excel, Word and a tiny bit of hardware.

Growing up, ‘computing’ was the opposite of creative. In fact, like all science and technology, computing was boring (this deeply incorrect perception is a story for another day). To me, a career working with computers meant systems administration. This was not surprising as in my hometown, the only people I knew who worked in ‘computers’ were the IT teacher, the school systems administrator and the people who sold my parents our first computer. They were all men. This probably didn’t help.

Seeing the Light

I got into web by accident - I wanted to create an online portfolio of my university work animations (I did a degree in film/photography/digital media) and having asked my then boyfriend for Dreamweaver, was presented with an Ubuntu install and book on HTML. My first portfolio was a disaster and I nearly gave up when I saw it in ie6. I cried when someone on a forum told me I had 350 errors in my HTML. But after a few more sites and a great deal of confusion, I had a great portfolio of online work to snag my first job in the industry.

I absolutely adore the creativity of designing websites. I love that I can craft something from nothing. I love mixing with colours, typography, shapes, and images. I love thinking about how the site is going to solve a problem, or communicate with the user. I love the satisfaction of knowing that people are actually using the thing that I built.

Even so, for a long time I avoided learning back-end development. I still had it in the ‘dry’, ‘boring’ and ‘difficult’ box. And that’s the thing - all the tutorials and books were boring (because they built things I had no interest in making) or poorly written, or difficult. They all lacked creativity.

After a lot of encouragement from my then-boyfriend-now-husband I finally decided to give it a go. I named 2014 my ‘year of python’ and set about building an application to teach myself Django.

Down the Rabbit Hole

I didn’t have many expectations about learning Django. I knew it was a good framework and that Python is a great first language to learn. I hoped that I would like it, but had no idea how much personal and professional satisfaction I would gain by hacking away at my application.

To my surprise I quickly learnt that web development is innately CREATIVE. And - by extension - that web developers are creative people. After all - what is programming if not coming up with creative solutions to problems?

The binary of creative vs technical that was so ingrained in my education (where most students are funneled into either an ‘arts’ or ‘STEM’ stream) fell apart. I realised that I could be a web developer, because I didn’t need to identify as a technical person - I could just be me.

Nicole Harris

Talking about PyPI on podcast.__init__

EuroPython Keynote - PyPI: Past, Present and Future

Video

Slides

Links and Resources

On Python Packaging

On PyPI / Warehouse

Statistics

Images

Thanks!

Addendum (6th Aug, 2018)

PyPI User Research

Conducting User Research for PyPI

Approach

Limitations

Results

Next Steps

Accessibility on Warehouse (PyPI)

What we’re doing well

Improvements

Next steps

How you can help

Addendum - 21st July 2018

My guest appearance on the Talk Python to Me podcast

User Testing Warehouse

User Testing Warehouse

Next Steps

Get Involved

Interview Series - UX & UI at PeopleDoc

Presenting Warehouse at PyCon France

Presenting at DjangoCon Europe

Designing Warehouse - An Overview

Our Goals

What We’ve Done

Making the UI Welcoming

Helping Users Overcome Obstacles

Ensuring the Site Is Inclusive

How You Can Help

Contributing Code

Participating in Usability Testing

Helping Rewrite PyPUG

Providing Feedback

Wrapping Up

Update (27th Feb, 2018)

Learning Python, Learning French - My Talk from PyConFr

My First DjangoCon

Talks

Sprints

Community

Beginning BDD with Django - Part Two

Contents

Revisiting Our Feature File

Dependencies

Folder Structure

Setting Up Our Test Environment

Creating Factories

Configuring environment.py

Running Our Tests

Writing Test Code

1. Given there are a number of interests

2. And there are many users, each with different interests

3. Given I am a logged in user

4. When I filter the list of users by …

5. Then I see … users

Wrapping Up

Beginning BDD with Django - Part One

Contents

Why BDD

How BDD Can Help

An Example

Feature Files

Lines 1-3: Defining the Feature

Lines 5-7: Setting Up the Background

Lines 9-12: Writing Scenarios

Putting It All Together

Refactoring

Conclusion

Tutorial : Implementing Django Formsets

Contents

Talking about PyPI on podcast.init