Understanding Public & Non-Public Interfaces

00:00 Public and non-public interfaces in Python. What is an interface? Well, when you are writing your code and you are using a Python package or a built-in function, you are in fact accessing that package’s functionality via its interface.

00:17 The interface is the way you interact with a package or a built-in function. That still sounds pretty theoretical, doesn’t it? I know, but don’t worry. You’ll see an example in a minute and it will become very clear after that.

00:30 But for now, just know that an interface can be public or non-public.

00:37 So what is the difference between the two? Well, a public interface is meant to be accessed by anyone. The objects in that interface are not prefixed with underscores.

00:48 So examples could be account or balance, whereas the non-public interface that is meant to be accessed by internal implementation only, and we will see an example of what that means.

01:00 Actually in the next lesson, we’ll see plenty of examples of what that means, but importantly these are prefixed with underscores. So they start with one or more underscores, for example, _account or __balance.

01:16 I note that the slides say meant to

01:20 because the naming convention doesn’t actually stop you from accessing the non-public objects. That’s why Python uses the term non-public as opposed to private.

01:31 And we’ll see some examples in later videos where I show you that you can actually access the non-public objects, but this is different from other programming languages such as C++, for example, where there are actually specific keywords to define private objects.

01:47 Now, how that works exactly is not for this course, clearly we are looking at Python and how it works in Python. And if you want to find out how things work in Python, what do you do?

01:58 Look at the PEPs. So please go back to PEP 8, the style guide. There you will find a section called Designing for Inheritance.

02:08 Public attributes are those that you expect unrelated clients of your class to use with your commitment to avoid backwards incompatible changes.

02:19 Non-public attributes are those that are not intended to be used by third parties. You make no guarantees that non-public attributes won’t change or even be removed.

02:31 So these guidelines are clearly written for designers, so it’s written from the point of view of a designer. Now you can be a designer where you are a designer when you are writing your own package or your own code, but you are also a user when you are using someone else’s package or someone else’s code.

02:48 So from this, what are the key takeaways?

02:52 Public objects are being used by others. That is the key point really. So public objects should be descriptive so that they are clear to the user. They should be intuitive, again, so that they are clear and stable over time.

03:06 This is the backwards compatibility that the PEP was referring to. Public objects, therefore, need to be properly documented because well, they will be used by others.

03:15 And then it’s important that others know what this function or this object actually does. Therefore, also objects that you are likely to change over time should remain non-public such that no third party uses those objects and therefore when you change it, their code doesn’t break.

03:33 And then lastly, for you as a user, objects whose names start with an underscore or multiple underscores in someone else’s code should be considered non-public and therefore should not be used.

03:46 Now here is another example of why it is important to stick to the Python conventions because many Python tools such as code editors or IDEs, code linters, and REPL apps rely on the leading underscore naming convention to distinguish between public and non-public objects.

04:07 Just to elaborate on that statement, let’s have a look at how IDEs might rely or at least take account of the naming convention of having leading underscores.

04:19 So the class, MyClass here has two methods: a public method, which does not start with an underscore, and all this method does is it prints the word “public”.

04:30 And then there’s a private method which starts with an underscore, and all that does is it prints the word “private”. We then have our if __name__ == "__main__": section where we create an instance of MyClass and then we access the public method of MyClass and then we access the private method of the class.

04:56 Importantly, currently, the IDE is not showing any errors or is not giving us any messages just to show you that the code works, let’s quickly run that.

05:09 So what happens here is that the word “public” is printed because that’s what we asked this statement to do here. And then the word “private” is printed as well because we accessed the private method of MyClass.

05:24 So the code works, but what I really wanted to show you is that you can change a setting and this is VS Code. It might be different for the IDE that you are using, but you can change a setting such that the private method is highlighted or it gives you a warning that this is a private method.

05:42 So how do we do that in VS Code? You press Control + Shift and P, and then you open the Preferences so open user settings and we open .json file, and at the very end of that file within the dictionary at setting, we have to adjust the setting and for convenience I’m just going to copy paste that in because it’s a bit long to type.

06:06 Just have to make sure that it lines up.

06:09 So what this is doing, this is another setting. So it’s the diagnosticSeverityOverrides and the reportPrivateUsage is an error.

06:20 So in other words, if there’s private usage suggested by the underscore or leading underscore, then we will get an error. So let’s save that and close the window.

06:32 You might have noticed that as soon as I closed the settings window, there was a red squiggly line that appeared under the line of code where we access the private method.

06:45 And if you hover over that, it will give you an error message or a warning saying that private method is protected and used outside of the class in which it is declared.

06:56 So this is an example of how IDEs rely on the use of the single leading underscore to distinguish between public and non-public attributes or objects.

07:09 In the next lesson, I’ll guide you through a real-world example to bring this theory to life. See you there.