What does it take to build a Python library that will be used by a large number of developers?
This happens all the time in open source.
Projects take off and become wildly successful.
What if you could sit down with the developers using your library and see how they take to it?
Well, over on the Azure team, Kate Olsewska and Johan Stenberg do incredible user testing for Azure's Python SDK.
Just to give you a taste, imagine a room with a computer, a couple of developers unfamiliar with the API,
a one-way mirror, and lots of feedback.
This is Talk Python to Me, episode 251, recorded Monday, January 27th, 2020.
Welcome to Talk Python to Me, a weekly podcast on Python, the language, the libraries, the ecosystem,
and the personalities.
This is your host, Michael Kennedy.
Follow me on Twitter, where I'm @mkennedy.
Keep up with the show and listen to past episodes at talkpython.fm.
And follow the show on Twitter via at Talk Python.
This episode is brought to you by Springboard and Clubhouse.
Please check out what they're offering during their segments.
It really helps support the show.
Kate, Johan, welcome to Talk Python to Me.
Hi.
Thank you.
It's great to be here.
Yeah, it's great to have you both on the show.
I'm really excited to talk about creating Python APIs and how you communicate those and document
them for Azure.
Azure is so huge.
And I haven't even done anything with Azure for a couple of weeks, probably.
Maybe even a couple of months, counting some vacation time in there.
And there's just so many things.
So these libraries are super far reaching.
So it's going to be fun to dig into all those, I think.
Now, before we do, though, let's start with your stories.
How do you all get into programming in Python?
Kate, let's start with you first.
Me first.
Okay, sure.
So my story is relatively short.
I started with Python as the first language that I picked up in my first intro to programming
class.
And it kind of stuck with me throughout.
Yeah, cool.
And did you start out in computer science just planning to go down that path?
Or did you study something else?
I was initially studying economics.
And kind of in a lot of data science that economists do, you know, there's a lot of existing
software.
But at some point, I figured there's more flexibility if you do some things on your own.
And that's when I started to pick up more of data science through Python.
And that's what led me into it.
Yeah, I never really thought of economics as having this super strong data science side
to it.
But the more that I talk to data scientists, a lot of them come from economics background.
It's pretty interesting.
Yeah, there's a lot of analysis that's done on like really large scale.
And there is a huge need.
And mostly what happens is that a lot of economists just work with data scientists to help them provide
the data and the analysis, while they just provide kind of contextual information.
But in the end, it's most efficient if you can do some stuff on your own.
Yeah, absolutely.
It's definitely great if you can solve your own problems and not go asking for help, right?
Yep.
Johan, how about you?
How do you get in programming in Python?
Actually, I did not start until five years ago in Python specifically.
At the time, we were looking at rebuilding the client libraries.
And specifically in that case, the command line interface for communicating with Azure.
We had one that was written in JavaScript.
And we decided that that needed some overhaul.
So we looked into doing that in Python.
So that's how I got started with Python.
Right.
And what you're talking about, this is not just the libraries that maybe Python people
might use.
This is the command line interface for working with Azure as a Java developer or as whatever,
right?
It doesn't matter what language you are.
Like, this is the language you guys decided to implement it in or move to, at least.
Correct.
So it gave me my first introduction to both Python, the language, but also the client libraries
that we had to use in order to implement the CLI.
But you're absolutely correct.
That was an application that we wrote in Python.
Right, right.
Where were you coming from before then?
What language?
Not surprising.
A lot of people at Microsoft write code in C#, in C++, although I haven't done much
C++ in the last decade or so.
But I've also written code in Visual Basic.
I'm probably one of the few people that have written Visual Basic.net code that ships as
part of Visual Studio.
So, but C# primarily.
Yeah, yeah.
What's the story of Visual Basic.net these days?
Is that still a thing?
I mean, I know technically it's supported, but it feels like the main story that Microsoft's
telling around their own internal languages is C#.
Most users, I'm actually not up to speed.
I haven't been on the Visual Basic.net team.
I left that in 2005 or something like that.
So I've kind of lost contact with my friends over in VB.net land.
Sure.
No, no worries.
How'd you get into programming in the first place?
I'm from Sweden originally.
We had a toy store in Stockholm, the capital of Sweden, and they had a wall full of home
computers is what they were called at the time.
Commodore 64, Svick 20.
As opposed to the machine sized ones?
As opposed to the PCs that became popular later on and all of that.
And there was always something fascinating about being able to tell a machine what to do.
Although a kind of archaic way that you have to tell it what to do would wrote things in
basic at the time.
But just having playing with it and getting it to print your name over and over again.
I think that was my first program as it wasn't Hello World at the time.
It was your one was here.
It was Hello, Johan.
But yes.
I don't know.
From that point on, I realized that that's what I'm going to do when I grow up.
That's what I did when I grew up.
Yeah, that's super cool.
Well, both of those are really great ways to get into programming and cool stories.
I guess another follow up question before we move off this intro bit here.
So Johan, you had said that your first exposure to Python was when you guys rewrote the CLI
in Python, which is good.
But then you also, to implement that, had to use all the Python libraries that other people
who wanted to automate Azure or talk to parts of Azure with Python had to use as well.
What was that experience like?
Was it like, oh, these are great libraries.
They're really well put together.
It was like, wait a minute.
This seems different than all the other stuff I see online.
It looks more like C# in Python.py files.
I have no idea.
I'm asking.
What was it like?
It was a little bit all over the place.
One thing that we do here at Microsoft is quite a few of what we consider to be the control
plane.
That is how you create resources in Azure.
Those are auto-generated from Swagger or OpenAPI, which means that they are auto-generated libraries
with all of the good and bad that comes with that.
Other libraries were what we consider to be the data plane that is actually using the service
software provision that, uploading blobs, things like that.
They were hand-authored.
So there was a wide variety of how, what the client libraries looked like, what patterns
they used in there.
So it was a little bit all over the place.
Yeah.
So maybe just define Swagger and OpenAPI for folks listening.
Not everyone's API developer.
Ah, sorry.
Sometimes I forget.
That's part of my life as well is reviewing REST APIs.
So...
Yeah, no worries.
You're deep in it.
Yes.
Deep in it.
It's a way of describing a REST API.
So basically, OpenAPI is an open standard that allows you to describe your endpoints, what
kind of data that they can accept and what kind of data that they will return if you call
them.
So it's something like you guys have maybe implemented your endpoints, your REST endpoints
and, I don't know, ASP.NET Web API or whatever you guys chose.
And then you added Swagger to it.
And then everyone else is like, hey, we need libraries for these.
We can auto-generate some Python libraries or JavaScript libraries or whatever it is you
can auto-generate off of Swagger.
Is that sort of how it went?
Yes.
So it's both that.
And we still do that.
We have, there's a requirement for all Azure services to describe their REST APIs using
OpenAPI.
And it has a tool chain both to generate libraries as well as documentation, reference documentation
and tooling for trying to ensure consistency among the REST APIs.
Yeah.
Oh, that sounds really fun.
Now, next thing related to this, I want to ask you what you do day to day.
And we got a sense of what you do quite a bit there, Johan.
But maybe give us the quick flyover and then Kate can tell us what she's up to as well.
Yeah.
So the two main areas of responsibility that I have is I'm the architect for the Azure client
libraries for Python.
So I'm responsible for the overall design guidelines that we have that are publicly available.
I'm trying to help the people on my team figure out what the common patterns should be, what
their handling should look like, what authentication should look like.
So that's one half of my job.
The other half of the job is to look at Azure's service APIs and try and ensure that we have
as much consistency as we can on that side as well.
Is it across different services or across different languages for a given service?
It's across different services for on the service API side of things.
The cross languages is a really interesting question because we have, I'm the architect
for Python.
We have, I have counterparts for JavaScript, TypeScript, Java for C#.net, obviously.
So what we are looking at is we're looking at these guidelines.
The capabilities have to be roughly the same for all languages.
If a service exposes a feature, all languages need to be able to expose that feature.
If a service has some specific failure modes or some quirks to it, everybody has to deal
with that.
So we're having discussions both how to best implement it in Python, but also making sure
that for all languages that we provide client libraries, that they all have the same capabilities
as well.
Right, right.
Yeah.
That's got to be an interesting intention.
Kate, how about you?
What do you do today?
I'm a program manager on the same team, but on my side of things, we like to call ourselves
just Azure developer experience, because one aspect of having that great experience with
the libraries is having great libraries.
But another is also making sure that the experience you get when you come to Azure as a developer
is that everything is straightforward.
If you go to the portal, we find the information that you need to get started and everything else.
So we like to work with other teams across Microsoft and across Azure to ensure that we bring that
consistency in other places as well.
My main job is to bring the voice of the developers using Azure into the designs that we have in
all of these places.
Cool.
That sounds really fun.
And you guys have some really neat stuff that we're going to dig into that you're using over
there.
The scale of Azure, kind of like I was saying before, it's a little bit, I mean, I guess if
people use AWS, they probably have a similar feeling.
Although I feel like Azure is even more so these days.
You just go there and it's like, you know, this huge menu of so many different choices.
It's a lot to keep track of and help people discover, right?
Yeah.
That's actually one of the main issues that we see for people who are just trying to, you
know, play around with these platforms.
And I think that applies across, you know, both Azure and AWS and everywhere else.
There's just so many different services to begin with that it might be kind of overwhelming
to know where you need to go.
So I think eventually our goal is to make sure that that choice becomes easier over time.
Have you guys thought of things like a beginner view or something, you know, for lack of a
better word, something that hides a lot of the stuff and just says, I'm a web developer
in this language.
Just show me the 10 things that I might care about.
Yeah.
I think we're trying to create some sort of tracks based on what we believe people might
be developing in our documentation so that it's easier to consume.
But I think, you know, maybe that's a good idea.
Just have a very simple beginner view.
Yeah.
Like show me everything.
I don't know.
It just, my experiences there has been, it's like, wow, I'm on a bit of a treasure hunt,
you know, to go through things here.
Yeah.
Very cool.
Now, you guys are also, Kate, you're also involved in some of the documentation and
tutorials and things like that.
Johan, are you as well?
Yes.
Yes, I am.
Yeah.
Actually, in our team, we were trying hard to have a greater push for creating better documentation
overall.
I think one of the problems with the auto-generated libraries is that that sometimes ends up being
not the best documented library in the end.
And that's why all of our developers really focus and spend time on writing better comments
and including more instructions for people to get started with.
Yeah.
Some of those auto-generated documentation things, it can be really tricky because it could
say like, you know, the function could be log in.
The documentation might be logs in user or upload uploads file, right?
It's just like one or two words or it just takes the name with a function and breaks it
out into like English-like words instead of compound words or whatever.
And it's just like, yeah, you can tell that, okay, this documentation, this is not going to
be helpful for me, right?
So it's good to have something really, you know, custom there, right?
Yeah, exactly.
Yeah.
One of the challenges, I guess, let me ask you, Kate, how much are you focused on Python
specifically and how much are you focused sort of cross-language working on this stuff?
I am focused on all languages to an extent because, you know, if we're creating some standards
for documentation that should apply across all of them, Python shouldn't be getting some
extra treatment just because it's Python.
I don't see why not.
Maybe that's just me.
Sure.
Let's document just Python, nothing else.
I was more asking, like, are you specifically on like the team that does the Python parts
and there's other people doing the same thing for JavaScript or are you like overseeing it
for all the languages?
Our split in terms of who cares about what is pretty complex on the PM team.
My focus was for Python in a sense of helping with user studies and helping with some telemetry
searches.
But in terms of all of these kind of overarching themes, I work with all of the languages.
Okay.
Yeah.
Cool.
This portion of Talk Python to Me is brought to you by Springboard.
Springboard offers online data science and machine learning education through their Machine
Learning Education Career Track program.
This is similar to an online machine learning boot camp with the difference that this career
track follows a project-based learning methodology where students work towards creating their own
portfolio of machine learning models.
And every student is paired with a machine learning expert who provides unlimited one-on-one mentorship
throughout the program via video conferencing.
This program was built for software engineers.
So to be eligible, you must have at least one year of experience.
You'll get a machine learning job guaranteed.
Springboard is the first company and still the only company in the U.S. to offer a machine learning
engineer career guarantee for students interested in changing careers.
That means either you get a job in the industry or your tuition is reimbursed.
So to get started today, just visit talkpython.fm/springboard or click the link in your
podcast player.
One of the challenges I can see here right away and your joke, Johan, sort of touches on it a little
bit.
I mean, I know you're joking, but you've got some endpoints, some cloud stuff that you want
to control and do things.
And every language has its own idiomatic way of working, right?
You know, Python has Pythonic code.
Other languages have, you know, whatever, whatever they call it.
Right.
But there's always an idiomatic way of doing things.
And sometimes that really lends itself to doing something quite different than other languages.
How do you trade off trying to make it so that somebody who's a C# developer working
with a Python developer, it's not like two different worlds, but also it doesn't feel like somebody
put C# or JavaScript into a .py file.
Yeah, you're absolutely right.
that's a constant tension.
And we've had plenty of discussions among the architects for the various languages here
on how to accomplish exactly that.
And the way that you iterate through things is different a little bit in Python than it
is in C#.
For Java, we have builder patterns for things.
A lot of interfaces, a lot of builders, a lot of patterns over in the Java world, for sure.
Yes.
So it is a challenge.
We're trying to make sure that we can talk when we talk about the abstract concepts, for
the most part that you can understand.
You can basically say if you talk about a specific thing, a specific noun, be that the blob or something
like that in one language, that you can map it down to what that means.
If I look at code in a different language, exactly what it looks like is going to be slightly
different because otherwise you're stuck with something that is going to be looking like
a specific programming language.
We certainly had that problem when I started here that we had some jokes.
Some of the usability studies that we had, the participants were arguing about what language
the original library was written in or the developer, what language they preferred.
Could they see the abstraction leaking through and go, I know, I think I know what this is.
Yes.
There was one of the early Python library usability studies that we had where they argued whether
or not it was a C# or Java developer that had written the Python library.
And it made me feel sad.
Neither of those are the right answer.
I don't know what the answer is, but that's not right.
Right.
Yeah.
Kate, you're back there laughing.
Do you have some stories like that that you experienced as well?
Yeah.
I mean, as Johan mentioned, being kind of blamed of over C#ying all of our libraries
was one of the, I think, initial kind of triggers that also made us want to explore the space
we're in and launch our team to begin with to make sure, you know, people no longer have
these doubts anymore.
You know, it's interesting, right?
Like, I'd like to hear what the user testing sort of uncovered for this.
But to me, when I use a library, I'm trying to write some program and then I'm like, oh,
I'm going to bring this library into the program.
And it's clearly not following the idioms of the language.
You can just tell.
You're just like, ah, there is something.
This, you just get this feeling like this wasn't really made for me.
It was kind of thrown together so I could still work with it.
But it's not for me.
You know what I mean?
As a whatever developer, right?
If you're Python and you're consuming something that looks like C# or you're a C#
developer, you're consuming something that looks like C++ or whatever it is.
It's not a great feeling like, oh, this is a this is the place they want me to be, right?
Yeah, no, absolutely.
I do think so.
Something that I've learned working with the other architects for the different languages
that each programming language community has its own personality as well.
And I found the Python users are generally extremely pragmatic, which is something that I very much
appreciate.
Yeah, I would say that's a pretty good classification, right?
They don't bring all these design patterns and these extra structures and whatnot in just
for the sake of saying it's well designed or well factored.
It's like, we'll do that if we need to.
But let's just put a function in a file and try that first.
Something like that, right?
Yep.
So, yeah, there are lots of other other discussions on what is the best way of doing React in some
of the other language communities.
I have not seen too many of those things show up in Python discussions.
Yeah, that's a tough challenge.
How do you guys, either of you or both of you handle this?
Because, yeah, every language has its culture and its community, but you can only immerse yourself
so deeply in so many different cultures, right?
And really get the zen of it.
So, how do you keep track of the other ones?
Or is that just you work with the other folks that are more those language experts or whatever?
The way our team is structured is that we have four separate teams with each of them has an
assigned PM, an assigned architect, and an engineering lead in the entire engineering kind of team.
We're really trying to become experts in that particular language.
So, it becomes easier to track this as, you know, we have kind of separate entities that are caring about each language.
Yeah, they have that expertise or whatever, right?
And they can just express that, sort of speak for their community at the meetings.
Yep.
That is my role on the architect board that we have for the Azure SDKs.
I try to bring the Python voice into the discussion and telling them where we are going to do something different
and what the reason for that is.
Yeah, for example, not from the Python universe of things, but from JavaScript, we were wondering what would be the best way to present, you know, JavaScript documentation.
Should it be Node?
Should it be JavaScript?
So, we just brought in.
I have no idea about anything JavaScript related.
So, I just brought in our engineering lead and our architect and kind of let them let me know better about what the community thinks about that particular space.
Yeah, interesting.
Well, there's just, you know, so many APIs and then you have to, you know, sort of cross product that with how many different languages are consuming those APIs.
It's really interesting.
So, one of the things I think would be fun to talk about is the test setup that you guys have, Kate, for user studies and observations.
Basically, the way we just approach trying to create a library to begin with is, you know, we have to learn better about the service itself.
And we start out by, you know, writing initial preview versions of the library with guidance from the architects, as well as closer work with the service team.
Once we have some sort of preview to work off, we set up some user studies.
We have a couple of labs in our building where we invite a lot of developers to come for, I think, two hours at a time.
Where we set up some basic tasks for them to complete using the preview library that we have.
You might give them the library to, like, blob storage and say, okay, use Python to upload this file to Azure blob storage.
So, or something like that, right?
And then just let them go?
Yeah, exactly.
So, we try to, you know, start with some simple tasks to see how these, you know, initial steps are going and then try to proceed to more complicated tasks later on.
And then basically see how they proceed with that.
We have kind of two different separate types of studies that we do.
One is focusing on the design of the API itself, where we often do not provide much documentation and see kind of intuitively if the naming makes sense and where do people end up searching for them.
Yeah, just auto-complete driven discovery.
Go with that and see what they do.
Right.
So, in that case, it kind of helps us to better understand what are, if, you know, our conventions of naming are discoverable and easy versus the other type of studies we have is to go more end-to-end.
And once we have some sort of set of docs to go off, see how people actually go about discovering it and seeing if there are any gaps that we have.
Yeah, quite interesting.
So, you're both checking the libraries and the API, but you're also checking maybe the documentation and the tutorials in that second case.
Yeah, exactly.
Because there is a lot of existing documentation for things that existed before us.
And making sure that, you know, all the places where people actually go to find it are updated and are not misleading is a big challenge overall.
Yeah, yeah, for sure.
I mean, I can't speak for Azure in general.
I know Azure's changed a lot.
So, that old tutorials don't make any sense anymore.
But in the Python space, that is a challenge.
You'll see tutorials written for Python 2 that'll tell people, like, well, go pip install virtual ENV so that you can create a virtual environment.
And it's like, no, no, no, that's already built into Python.
It's a module, VNV.
Yeah.
We don't need these things.
Like, there's these other steps.
Or even there's new ways to install Python into Windows, right?
Like, from the Windows Store and whatnot.
So, it's got to be a constant challenge of, like, that stuff was put there to help people.
And yet, it's kind of in the way now.
It'd be better if you didn't put anything.
And they might just have to go search for it and maybe discover the right way.
Yeah, I think for Python specifically, there has been an effort on our side to also try to consolidate all sorts of guidance, exactly like you mentioned, with a virtual environment that is consolidated into guidelines on how we are supposed to write tutorials.
I think it's still at a draft stage, but it's something we're definitely looking more into to make sure that, you know, the guidance we provide for the tutorials and similar texts also makes sense for the set of developers and for the language.
Yeah, this question for either of you.
How do you all deal with telling people to get started in Python?
Because on Windows, until recently, they didn't have the Python 3 command, right?
Steve Dower got the new version of Python into the Windows Store, and it comes with Python 3.
So, that's one thing that you can just say, always type Python 3 to get started.
But I've always found it very tricky to say, if you're on Windows, you do this.
If you're on Mac or Linux, you do that.
And, like, you kind of have to replicate that either-or bit through everything.
How do you all deal with that?
Today, it is either-or kind of for your operating system go here kind of thing.
We're doing less of now, and I think what it used to do more of in the past was that every getting started document had all of the instructions on how to set up Python first,
which meant it was not until page 3 or something like that that you got to what we're actually trying to tell you.
So, now, most of the getting started documents are that, assuming that you have Python installed.
And, by the way, if you don't know how to do that, go here.
Right.
So, you just have that one little blurb at the top of the document.
Yeah, that makes a lot of sense.
Now, I do want to come back to this lab that you have, Kate, because I think it's really interesting from a couple of angles.
But let me try to describe what I think the lab looks like, because I've seen some pictures and whatnot of it in action.
But this might not be the same thing.
So, the one that I saw, there was basically a room with some computers.
Some developers can go sit down there and either, like, group program or do separate programming.
But then there's also a one-way mirror, and you could sort of screen share.
You could watch what they're doing on the screen from behind the mirror or somewhere else
and sort of critique, you know, how well your library is holding up to them, poking at it, and things like that.
Is that basically what it is?
It is pretty much how it is.
So, we do try to bring two developers at a time to do pair programming.
We've kind of noticed that it's much easier for people to be more open about what they feel about the libraries and the experience overall.
It's kind of more natural to speak out and comment and see how it feels.
It's also usually easier to unblock the other person if one of them doesn't have experience in something.
Yeah, I can imagine from a user testing angle that if there's more than one person,
person that are working on it, they're going to just communicate verbally with each other because it's weird to just sit there and work with not, like, sharing what you're up to.
But that's exactly, like, what you would like them to do for you to understand what they're doing, right?
Exactly, exactly.
So, even some, you know, more random comments are always great.
And we've had some people be very open about what they thought at the time of, like, oh, you know, this is crap.
Like, this needs to change.
I don't understand why I'm even looking at this.
And kind of having another person there, I think, makes it less awkward for them.
Because you can imagine sitting in a tiny, tiny room, you know, just you and a computer in front of you, knowing that you're being observed by X amount of eyes.
It's a pretty stressful situation if you're on your own.
Yeah, the other person will help you forget that there's all those eyes or thoughts thinking about what you're doing.
Pretty interesting.
On our side of things, we also try to bring in, you know, a lot of people.
So, all of the devs that are actually working on the library try to always come to the study to see how their libraries are performing.
So that it's also easier for them to kind of understand how, you know, how users interact with the libraries.
And to understand where the struggles are.
And makes it kind of easier for them to understand how important it is to make it really good.
Yeah, yeah.
You think, oh, that's no big deal.
People will figure that out.
We don't need to do this.
And then you see four people stuck for 15 minutes trying to do it.
You're like, oh, actually, okay.
I see.
Exactly.
How often do you run these studies and how many people go through them?
We are pretty much booked all the time.
I think we have user studies, if not every week, then every other week, depending on what we're currently working on.
So we have usually, we manage to do, I think, two groups of studies per day, which is four people then per day.
Sometimes if there is something in particular that we're trying to test out, we can use two.
So that would mean most eight people a day.
Yeah.
Okay.
Well, the reason I think this is so interesting is because there are so many people creating packages and libraries and Python for others to use.
And many of them are extremely, extremely popular, right?
You know, over on PyPI, we have 215,000 libraries at the time of the recording.
You can go over to place up PyPI stats, I think.
Mm-hmm.
And you can check that out.
You can see the most downloaded libraries, right?
It's pretty cool.
There's a bunch that are like over, you know, well over a million downloads a day.
So there's these libraries and they're just being used in so many, by so many people in so many places.
And yet my feeling is that most people who build these libraries have very little visibility into how people feel about them until they raise to the level of like a GitHub request or a bug sort of complaint or something like that.
Right.
And having this discoverability and ability to observe people working on your libraries, it must be really interesting.
Yes, absolutely.
I mean, it's very gratifying when you hear someone talking about the library that you built in a positive way.
Yeah.
It can be very humbling if you thought that you had a great idea that turns out that no one understands how to use or may even have other choice words for the experience that they feel like they were exposed to.
Yeah, yeah, sure.
I had a rough day at work.
People hated what I built.
I thought it was great.
That's pretty harsh, but it does allow things to get pretty polished, I suspect.
So, Johan, do you have some examples of things that you've changed or realizations you've had through some of Kate's studies?
One of the experiences is you touched on the tab completion kind of discovery of things, but the Python community is extremely diverse in how they use things.
I think about half of the people that we've had in the usability study did not use any form of IDE at all.
Yeah.
When they did things.
Yeah.
So you let them pick their IDE.
It's not like, hey, we're all using Visual Studio Code because it'll work with all the languages and it's consistent or whatever.
You said, if you want to use Emacs, knock yourself out.
If you want to use PyCharm, go for that.
Is that how it went?
The last couple of studies, I think we set it up using VS Code, but we've certainly had PyCharm.
We've had people that even if you have VS Code in there, they only use the, well, they use VS Code as an editor at most.
And then they dropped into the terminal window and run everything interactively or run things through REPL immediately.
The use of a debugger, similar thing there.
I think there was one quote that one of the participants had that, yeah, I use a debugger for simple things, but if things get complicated, then it's pretty print all the way.
It's so funny.
I'm laughing because to me, it's like the opposite, right?
I'll print out something like, oh, this is getting hard, man.
I'm going to have to use a debugger and go figure this thing out.
Yeah, but it's an insight into how people feel and what people use and how important it is to make sure that things work well, that you have a good, that you implement Dunderstir and REPR so you can print out an object and you get some useful information.
Right, right.
In fact, people use it that way.
So understanding the importance of that is something that I've come to appreciate more.
Right, right.
Because if you just print it out, especially if you're in the non-IDE situation and you don't know what the properties are, and maybe you got something like a blob response object, it would just say blob response, add memory address, such and such, right?
As opposed to here's the URL or the bucket and whatever, right?
Like, I think that actually is a good point in general for libraries to consider the Dunderrepper and Sturr stuff so that not just if you actually just want to print it out, but those appear all over the place, right?
Those appear in debuggers.
They appear potentially in log files.
There's all kinds of stuff where having that is just like, it's just delightful.
You're like, oh, I can just see what this is right here.
I don't have to do extra work because somebody put in like a nice little repper that's good enough to know what's happening.
Right.
So there are many of those small things that are there.
I'm trying to reduce the number of types that we have in our libraries now because in order to call an API, if you want to call that from the REPL window, it's much easier to just use scalar types, for example.
And we have the wonderful keyword-only arguments in Python that makes life easier, whereas in JavaScript, I would create option objects with lots of properties on it.
Right, because in the option object, you could have the default value, but in Python, that's just part of the function.
Right.
So these kind of things that have changed a little bit in how I look at libraries.
This is interesting about these sort of compare and contrast libraries, trying to do exactly the same thing with people that know the system really well.
I think that's super interesting.
And I feel like a lot of that pragmatism that Python has is because there's a lot of flexibility in the lower-level stuff, right?
Like keyword-only arguments with default values and stuff allow you to avoid certain patterns or a global variable in a module is kind of like a singleton.
That's what you need.
You don't need a whole class for that and so on.
What was your experience coming from these different languages and seeing that across teams?
Is that about right or how has it been?
Absolutely right.
I still review Python code from other teams that come in and you can see where they're coming from, where they have extremely deep class hierarchies and things like that.
It makes sense if you wrote code in C# or Java, but type safety is not the same thing in Python as it is in C# where you will get the compiler error if you try to call something that doesn't exist.
There are other patterns that you can introspect things in Python that makes it more powerful.
This portion of Talk Python to me is sponsored by Clubhouse.
Clubhouse is a fast and enjoyable project management platform that breaks down silos and brings teams together to ship value, not features.
Great teams choose Clubhouse because they get
flexible workflows where they can easily customize workflow state for teams or projects of any size,
advanced filtering, quickly filtering by project or team to see how everything is progressing,
and effective sprint planning, setting their weekly priorities with iterations and then letting Clubhouse run the schedule.
All of the core features are completely free for teams with up to 10 users.
And as Talk Python listeners, you'll get two free months on any paid plan with unlimited users and access to the premium features.
So get started today.
Just click the Clubhouse link in your podcast player show notes or on the episode page.
Kate, one thing I want to come back to because I do think it's really interesting and it's a challenge to this testing that you talked about is this not using an IDE or something that has some kind of
completion story for working with the code that Johan talked about.
What do you do if somebody wants to use one of those non-assisting editors or you're working with a language that doesn't provide enough information to actually get that even in tooling that would otherwise show it,
like some parts of JavaScript or something like that?
So as I mentioned before, we have a couple of different types of studies that we have.
So in cases where we can't rely on people discovering things on their own, we provide them with documentation.
We set up a couple of experimental documentation sites, which we can iterate on pretty quickly where we just direct people to a site and they can look at reference documentation.
I see.
So here's the SDK functions and types and whatnot.
Go look at that if you don't actually want to say dot and see the list or maybe an addition.
Yeah.
What about code that you all put into documentation?
Right.
You've got documentation for Python.
You've got documentation for JavaScript.
You both have these examples.
These libraries are changing over time.
The endpoints are changing potentially and, you know, extending or having better ways to do things.
How do you deal with that kind of stuff?
And do you have somebody go through and just go, all right, time to retry all the tutorials?
Or what do you do there?
Okay.
So there is a couple of different things we were trying to do.
So all of our packages live on our GitHub.
And one thing that we have already implemented for a couple of languages, but not all, is exactly as you mentioned.
It's kind of challenging to keep control of all of the code snippets and samples we have all across docs, all across all of other places.
So one thing that we are trying to do is to write tests that, you know, we test all the time on an ongoing basis and basically be able to pull out snippets from these sources into our readmes and then eventually into docs.
So that's something we have been putting a lot of work in.
Already, most of our stuff in our GitHub should be fresh because of this.
And we're now trying to ensure that the same thing happens when you're going to docs as we cross kind of reference our repositories.
Yeah, that's really cool.
You know, the challenge is that the little code snippet might need other stuff set up all around it, right?
Right.
The good thing is that usually in terms of the setup that's around it, that doesn't change as often because it's most, you know, having an instance of a service running or some sort of setting up the environment, which shouldn't change that often.
Yeah, I'm thinking of like a tutorial that says, first, import this thing.
Then a little bit later, it says, oh, make sure you set this connection string.
And then a little bit later, it says, here's how you download a file or whatever, right?
And you want to test the, here's how you download the file bit.
Like the stuff that comes before it still has to happen, but it's not part of that snippet.
Do you guys have examples like that you run into?
Yeah.
Yes.
So we do have that.
We have the, we're using things for generating a lot of this.
So using the literal includes.
So you can basically have a comment in the code that says this, this snippet or this part of my function or method corresponds to this example in there.
So when you run through the whole thing, it will do the setup and you can spread.
I see.
It'll like chain them together or something like that.
Yeah.
Okay.
Yeah.
The challenge is to keep everything up to date, as you alluded to.
If there's new functionality, we can, it's relatively easy or not impossible to make sure that things continue to work, to make sure that things are using the best practices.
If new best practices have come to light is much more challenging.
Right.
There's an old way of doing things.
Of course, it still works because you wouldn't break it for old software, but you don't want them to do that anymore.
Right.
So writing these examples, it's a little bit like giving someone a puppy.
It's going to be work forever.
That is true.
Yeah.
You got to walk it every day, even in the rain.
Yeah.
How about testing these libraries?
What do you all do for making sure that your library up to Azure or whatever service it's talking to is still good?
That's challenging.
We were talking at the Python meetup here in Portland about this.
And it's like, what if I wasn't connected and I wanted to run my test?
How do I even get that to work?
Or how do you test against real cloud environments, but you don't actually want to create a whole bunch of cloud environments?
You just want to see if the API is still hanging together or something like that.
It seems like a challenging thing to mock out all of Azure.
Yes.
So for what we're using is that we're using a recording framework.
So basically record all of the requests and responses.
Oh, interesting.
Okay.
Because it's very challenging.
And I, especially since we want to be able to take contributions from the public, we want them to be able to write tests and run tests, obviously.
But as with all clouds, it costs money to run things in the cloud.
And we don't want to charge.
Yeah.
Some are cheap, but some of them are really quite expensive to just do a little bit with.
Right.
If you're going to provision, I don't know, a certain type of VM with a GPU because you need to test the GPU a bit.
I don't know.
All right.
That could be expensive.
Yeah.
So what we have is that we make these recordings available so that you can run tests against these recordings.
It's still challenging to come up with new tests if you want to contribute to new tests.
Honestly, we don't have a good solution for that today.
But that's, we're using these recordings as much as we can.
And then we run, we call live tests on a nightly basis to make sure that things still work when actually using the services.
The recording is not lying.
The recording is not out of date, right?
What library are you using for this?
Is this a Python library?
Yes.
It's VCRPy that we're using now.
VCRPy.
That sounds very cool.
Or PyVCR.
Yeah.
If you go to our GitHub repository, github.com/Azure slash Azure dash SDK dash for dash Python.
Short name, I know.
But you can see that.
It rolls off the tongue, doesn't it?
Yes, it does.
Yeah, that's cool.
You can see how you guys are using it there.
Yeah, this is really cool.
I hadn't heard about this, but I'm sure that'll be useful for people out there in general, right?
Not just for people working with Azure tests.
Yes.
And this is not the library that we have produced.
This is an open source component.
Yeah, absolutely.
So how do you deal with...
It's still hard for me to get my mind around how many challenges you have for trying to keep all this stuff consistent.
So you've got all these different endpoints.
You've got these different languages.
How do you collaborate at the documentation level for, okay, we're going to create this new thing that helps people use this.
The JavaScript team's got to do it.
Other teams got to do it.
And they got to be consistent.
What guidelines and advice do you have for that?
For the documentation specifically or for the designs?
More for the documentation, I guess, is what I was asking.
Although both are interesting.
But there's a lot of people or companies out there that have multiple technology stacks talking to their same thing.
What advice do you have for them to help all the different consumers evenly?
One thing that we are trying to do is to, first of all, better understand in terms of these different technology stacks, what are the most kind of often used patterns?
And that kind of informs how we write the quick starts and the tutorials.
On our side, the process, the way it looks is that our developers writing the libraries provide the reference documentation and then include some sort of basic guidance of what they see fit for the readmes that we have on our GitHub.
And then for each service, we have a content development team that kind of tries to take it and write a more, some sort of a tutorial that's more digestible by all sorts of different audiences.
And they have a better understanding of what exactly they need to provide for these particular use cases in these different scenarios.
Okay.
So there's like a canonical example.
And this is what we wanted for here.
And then make a JavaScript version, a Python version, and so on.
Right.
Exactly.
Okay.
That's quite cool.
So this whole user testing of people consuming libraries, it's really interesting.
And like I said, with the PyPI examples and those popular libraries, no, I suspect very few people are doing that.
A few exclude like the Azure libraries and other big companies.
But Opus Horse teams, they have these sprints and they have other feedback mechanisms.
All the stuff we talked about.
Do you have any advice where people might be able to recreate a little bit of this?
You know, maybe at the end of PyCon, have a sprint where instead of trying to add new features, it's like, let's do some user testing for people who are attending the conference and are very passionate about our library.
Or maybe try to grab somebody who's used the other library that's, you know, like Django versus Flask or something and have them come over and, you know, work in our world for a little bit.
You know, without having one of these labs and whatnot, but maybe using things like LiveShare or something.
What advice do you have for bringing some of these cool practices that you guys are doing and applying to your libraries to, you know, maybe much smaller groups or open source projects?
I can start and Johan can nod in.
But in terms of the conferences, I think that's an amazing idea.
And that's exactly what we're doing.
In November, we're attending a Microsoft conference, Microsoft Ignite.
And that's exactly what we're doing.
We had a couple, you know, stands set up, allowing people to kind of try things out on their own, as well as take surveys based on the feedback that they would have gotten by completing some basic tasks and kind of taking that down and kind of informing for their designs.
So, yeah, I think it's absolutely a great way to easily be able to work with people directly if you don't usually have that in person.
Yeah, it seems like it would be a cool thing for conferences to set up, right?
I mean, at Ignite, you guys set that up and that's really cool because you're doing that sort of stuff.
But I'm thinking at PyCon or some other, you know, major JavaScript conference or something, right?
The conference organizers could have a section where, you know, you could sign up.
Hey, I'm this library developer.
I'm on this team.
I want to have people go through my stuff.
And I just think it would be great.
I mean, I have no ability to set that up or anything.
I can throw ideas out there and maybe people run with it.
But it seems like it'd be really cool.
Yeah, that seems like a really good idea.
One challenge I think that we've seen with that is that very often people are happy to provide some feedback if this is something they really care about.
But if that's not the case, then usually they would expect some sort of swag or something in return, which is fair.
It's fair.
And as companies, it's fine, right?
It's easy for Microsoft to put together a certain amount.
But as a solo developer on an open source project, it's much harder.
But, you know, maybe like a cool little badge that's got the picture, like a little logo and like, you know, I helped improve this at PyCon or something.
Or I helped improve Flask or whatever.
I think people can make it work without too much involved.
Yeah, that sounds like a good idea.
Yeah.
Johan, what do you think?
You can look at it as a contribution.
It may not be in the form of source code as well.
All right.
So having the contribution somewhere in and who contributed to the last release, you know, use relative feedback from people.
That's a pretty good piece of currency to work with that they do have something that they could hand out easily, right?
You don't have, you know, little robots that you can hand out for everyone who helps as an open source developer.
But you do have, like you said, credit.
That's cool.
Yeah.
And it's important as well to be clear on the fact that we have seen a little bit of bias that people want to be nice to you when they give feedback.
But what you really need is the harsh feedback as well.
So that's one thing that I think we're getting better at making clear that the participants that we want to hear the good and the bad and not just the good.
Right.
Tell us the truth, not just what you think we want to hear, even though it won't make your day not as good, I guess.
Right.
Yeah.
So nice.
All right, you guys, we're getting short on time here.
So let me just ask you the final two questions and wrap it up.
So Kate, we'll go with you first.
If you're going to write some Python code, what editor do you use?
I recently started using VS Code and have been enjoying it.
Yeah.
You guys are doing a lot of cool stuff with VS Code.
It's definitely growing quickly.
Johan?
Yeah.
VS Code is probably my go-to editor right now, but I try to switch between them just to get a feel for what the experience is for using our libraries and the different editors.
Yeah, sure.
You definitely want to know, like, well, what's the experience in Sublime or what's it like in VI or whatever, right?
Right.
Sure.
I switch between them basically every week.
I use a new editor.
That's got to be a little hard.
I mean, I know you get used to it and all, but.
Plenty of mistakes.
Just, yes.
Yeah, I bet.
And then I'll throw this out to both of you.
Either you can throw something in a notable PyPI package.
Some library out there that you're like, oh, this thing is super cool.
We'll use this.
Maybe people haven't heard of it.
And if you want, you're welcome to use VCRPy.
Have you got another one?
Throw it out there.
That's a good question.
That one I would have to think about a little bit.
All right.
How about VCRPy?
That's a good one.
Is it PyVCR or VCRPy?
Yeah.
There is a VCRPy and it sounds like it's the right one, but I don't want to recommend swapping it to the wrong one to people.
Yeah.
Yes.
VCRPy.
Okay, cool.
Yeah.
That's if you have things that are really hard to mock out and there's a complicated exchange, that seems like that's a pretty cool way to do it.
Yep.
Nice.
All right.
Final call to action.
People are out there.
Maybe they work at a big company.
They've got a set of APIs they've got to document across languages or they work at some other company that exposes their API to the world and they've got a document.
What advice do you have for them?
Take some of these things you've learned and apply it in their world.
It's not free to provide a good developer experience for people.
So understand that you need to, if you want to have a good developer experience, you need to invest time and effort into doing it.
So if you think that you can get away with having the same documentation for every language, auto-generate things, you will get part of the way, but it will not be great.
Yeah, absolutely.
I'll definitely show.
Kate, what do you think?
I think another important aspect is how, you know, ensuring that whatever you provide is really well documented.
It doesn't matter, you know, how much work we put into making sure that things are consistent and idiomatic.
In the end, people rely heavily on using documentation.
So making sure you create an easy and kind of consistent story around that is super important.
Awesome.
Good advice.
And thank you both for being here and sharing what you're up to.
It's really cool.
Thanks for having us.
Thank you.
Yep.
Bye.
This has been another episode of Talk Python to Me.
Our guests on this episode were Kate Olasueska and Johan Stenberg, and it's been brought to you by Springboard and Clubhouse.
Become a machine learning professional with Springboard's online bootcamp and get a job, guaranteed.
Visit talkpython.fm/springboard to apply today.
Clubhouse is a fast and enjoyable project management platform that breaks down silos and brings teams together to ship value, not features.
Fall in love with project planning.
Visit talkpython.fm/clubhouse.
Want to level up your Python?
If you're just getting started, try my Python Jumpstart by Building 10 Apps course.
Or if you're looking for something more advanced, check out our new async course that digs into all the different types of async programming you can do in Python.
And of course, if you're interested in more than one of these, be sure to check out our Everything Bundle.
It's like a subscription that never expires.
Be sure to subscribe to the show.
Open your favorite podcatcher and search for Python.
We should be right at the top.
You can also find the iTunes feed at /itunes, the Google Play feed at /play, and the direct RSS feed at /rss on talkpython.fm.
This is your host, Michael Kennedy.
Thanks so much for listening.
I really appreciate it.
Now get out there and write some Python code.
I'll see you next time.
Bye.
Transcription by CastingWords