WEBVTT

1
00:00:01.790 --> 00:00:06.660
so getting back to doc strings again now for
simple functions and classes you

2
00:00:06.660 --> 00:00:10.790
doc string can really just be a single
line summary in which case just included

3
00:00:10.790 --> 00:00:14.570
all on one line with the quotes on the
same line you can see here obviously with my

4
00:00:14.570 --> 00:00:18.460
doc string here I've got the quotes in different
lines because we got multiple lines of

5
00:00:18.460 --> 00:00:23.540
text their but often you want to provide more
information then there for multi line

6
00:00:23.540 --> 00:00:26.759
doc string may be more appropriate
will be more appropriate in the

7
00:00:26.759 --> 00:00:31.960
circumstances so the first line of a
multi line doc string should be a

8
00:00:31.960 --> 00:00:36.730
brief summary with further details
included after a blank line so can see

9
00:00:36.730 --> 00:00:40.080
here we've got the brief overview of
what this class is about a blank line

10
00:00:40.080 --> 00:00:41.930
and then we got more information

11
00:00:41.930 --> 00:00:45.870
after that blank line now it can
be difficult to strike a balance between

12
00:00:45.870 --> 00:00:52.650
being to brief and to verbose and the
doc strings for this song class are a little

13
00:00:52.650 --> 00:00:56.040
bit too verbose at the moment by
themselves they are ok but the doc

14
00:00:56.040 --> 00:00:59.570
string for the init method doesn't
really add anything that isn't already

15
00:00:59.570 --> 00:01:03.370
included in the doc string for the class in
other words this doc string down here

16
00:01:03.370 --> 00:01:07.170
doesn't really give us much more
information other than introducing a typo their

17
00:01:07.170 --> 00:01:14.530
which I'll fix then it has already been specified in this class doc string and just to see in this action we

18
00:01:14.530 --> 00:01:18.670
can see this a bit better by looking at one of the uses for
doc string which is providing help

19
00:01:18.670 --> 00:01:23.530
now strangely IntelliJ gives a warning
about an unexpected argument to the help

20
00:01:23.530 --> 00:01:28.540
function this actually cause is caused
by the doc string for help itself now I'm

21
00:01:28.540 --> 00:01:32.869
gonna come back to that but for now when we
run the program after this line

22
00:01:32.869 --> 00:01:35.610
24

23
00:01:35.610 --> 00:01:38.720
type help.....

24
00:01:38.720 --> 00:01:46.720
and you can see we've got this warning here unexpected argument so that
actually caused by the doc string for help

25
00:01:46.720 --> 00:01:47.670
itself

26
00:01:47.670 --> 00:01:51.750
now I'm gonna come back to that but for now if
you run the program just right click and

27
00:01:51.750 --> 00:01:56.310
run song to make sure I'm running the right Python file and scroll up a

28
00:01:56.310 --> 00:01:59.180
little bit

29
00:01:59.180 --> 00:02:04.790
you can see the documentation that is for this particular class so you could see here

30
00:02:04.790 --> 00:02:08.119
the doc string is used by the help function to
provide information on the song class so

31
00:02:08.119 --> 00:02:13.240
by calling the help function which is part of
Python its automatically added this and

32
00:02:13.240 --> 00:02:16.510
put this information in the form of
documentation which we can read

33
00:02:16.510 --> 00:02:21.250
because they added this bit here data inscriptions define here but also this bit here grabbing

34
00:02:21.250 --> 00:02:27.060
the information from our doc strings so close that down and the other thing we can do we can

35
00:02:27.060 --> 00:02:32.459
request help on a particular method so if we go and
change line 24 here so instead of just

36
00:02:32.459 --> 00:02:39.000
doing generic help for the song class so gonna
change to do just add so I'm going to get

37
00:02:39.000 --> 00:02:48.620
some help for the init method so.....

38
00:02:48.620 --> 00:02:53.100
what we want to do is we don't want to call the init method we want to just get

39
00:02:53.100 --> 00:02:56.370
some information get some help on it so
make sure I've remove those parenthesis

40
00:02:56.370 --> 00:03:02.300
as you saw me doing and if I run it again we can see now helps gonna come back and show

41
00:03:02.300 --> 00:03:06.970
us the information just for the init method
itself and not for the entire class that was

42
00:03:06.970 --> 00:03:12.670
their last time and the other thing you can do is you can
just print this out so I can comment out line 24

43
00:03:12.670 --> 00:03:21.210
.....

44
00:03:21.210 --> 00:03:28.850
so via the doc attribute if you run
that we've got to class doc string

45
00:03:28.850 --> 00:03:32.520
there that is another way of accessing
information instead of using the help

46
00:03:32.520 --> 00:03:36.660
function but the big difference their is
where as help will display the doc string

47
00:03:36.660 --> 00:03:38.360
for all the methods as well

48
00:03:38.360 --> 00:03:43.040
printing it out in this way as we just did their with the
print only gives the doc string for the object

49
00:03:43.040 --> 00:03:47.320
specified which in this case is the
class so to display the doc string for the

50
00:03:47.320 --> 00:03:52.510
init method then we have to specified
explicitly so if I show you what I mean

51
00:03:52.510 --> 00:04:01.700
so it won't be just init method we'll have to do something like.....

52
00:04:01.700 --> 00:04:11.820
....and if we run that we've got the song
init method showing their underneath the

53
00:04:11.820 --> 00:04:17.200
output which was from the class so really
at this point in the courses shouldn't

54
00:04:17.200 --> 00:04:21.550
be anything really surprising about the
output and if you believed on what I have

55
00:04:21.550 --> 00:04:25.940
said that everything in Python is an
object then this should really be

56
00:04:25.940 --> 00:04:30.090
anything surprising about the way we just access it
just in case though what I've done there is

57
00:04:30.090 --> 00:04:35.560
print the doc attribute of the init method
now functions and methods in Python are

58
00:04:35.560 --> 00:04:40.900
also objects so they have attributes just like
any other object so the doc string as

59
00:04:40.900 --> 00:04:46.720
we have defined it for the init method here the code on line 11 through 18 the

60
00:04:46.720 --> 00:04:51.340
doc string for the init method is really
too much and adds nothing as I mention to

61
00:04:51.340 --> 00:04:56.450
the class doc string so I'm gonna remove it
and but I will also add it back temporarily by

62
00:04:56.450 --> 00:05:00.200
assigning the string to the methods doc
attribute so I'm gonna do that I'm going

63
00:05:00.200 --> 00:05:02.530
to just copy this and I'm just going to

64
00:05:02.530 --> 00:05:10.360
and get rid of that for now and what I'm going to do is show you another way that we can add the documentation if

65
00:05:10.360 --> 00:05:22.260
we wanted to and we can do is this way under the print I can put...

66
00:05:22.260 --> 00:05:32.300
....

67
00:05:33.550 --> 00:05:43.220
....

68
00:05:43.220 --> 00:05:50.610
....so lets run that and you can see we got the class

69
00:05:50.610 --> 00:05:55.680
doc string there and also the
init doc string showing so that's just an

70
00:05:55.680 --> 00:06:00.920
alternate way that you can add a doc string if you
want to create it in code that way now note

71
00:06:00.920 --> 00:06:07.280
that this code won't work in Python 2 in
Python 2 the doc attribute which we've

72
00:06:07.280 --> 00:06:08.500
written to on line 19

73
00:06:08.500 --> 00:06:13.250
its not writable on the Python 2 but that's not really a problem

74
00:06:13.250 --> 00:06:16.820
because obviously you wouldn't really do
that in a real application if you gonna

75
00:06:16.820 --> 00:06:20.450
provide a doc string and probably should be
included with the object as I

76
00:06:20.450 --> 00:06:27.570
did originally if the code that I cut out that was originally
lines 11 from 11 onwards but this does

77
00:06:27.570 --> 00:06:33.230
demonstrate that methods can have a attributes and gives you a taste of the power in Python so

78
00:06:33.230 --> 00:06:40.250
in Python if you want to do it thhen you probably can that is the general philosophy even if it's not a good idea

79
00:06:40.250 --> 00:06:44.680
to actually do that so lets move on now
and continue with our record collection

80
00:06:44.680 --> 00:06:49.550
so the next step is to create an album
class its going to store the songs that will

81
00:06:49.550 --> 00:06:54.020
make up an album so what I'm going to do is
delete the doc string code that I used to demonstrate

82
00:06:54.020 --> 00:07:01.400
the doc string attribute and add a new class so basically
delete all this code from line 16 onwards which we

83
00:07:01.400 --> 00:07:06.660
don't need anymore let's go ahead and
create this class album

84
00:07:07.390 --> 00:07:12.830
.....

85
00:07:14.320 --> 00:07:25.570
...again the convention is that extra blank line

86
00:07:25.570 --> 00:07:40.340
their and....

87
00:07:40.340 --> 00:07:43.340
....

88
00:07:45.430 --> 00:07:58.660
....

89
00:07:59.960 --> 00:08:02.960
....

90
00:08:04.030 --> 00:08:24.860
....

91
00:08:24.860 --> 00:08:27.100
...

92
00:08:27.100 --> 00:08:31.240
....

93
00:08:38.120 --> 00:09:31.420
....so that is our class album doc string so lets start writing a bit of code so we define our init method....

94
00:09:31.420 --> 00:09:45.030
....

95
00:09:47.270 --> 00:10:02.430
....

96
00:10:02.430 --> 00:10:13.380
....next we want to create

97
00:10:13.380 --> 00:10:17.880
this add song method but before we do that
we need to then save the track

98
00:10:17.880 --> 00:10:19.589
so....

99
00:10:19.589 --> 00:10:22.640
.....

100
00:10:23.990 --> 00:11:01.660
....

101
00:11:02.440 --> 00:11:10.050
....

102
00:11:11.710 --> 00:12:04.240
....

103
00:12:04.240 --> 00:12:15.540
.....

104
00:12:15.540 --> 00:12:27.590
....

105
00:12:27.590 --> 00:12:32.770
.....so once again there's really
nothing that can be said in the doc string

106
00:12:32.770 --> 00:12:39.570
for the init method that isn't covered in
the class doc string so its worth adding a note

107
00:12:39.570 --> 00:12:44.360
about the add song method though so following the guidelines of pep 257 which I hope

108
00:12:44.360 --> 00:12:48.590
you've read it by now the first line is a brief
summary of what the method does then the

109
00:12:48.590 --> 00:12:52.080
individual arguments are documented and
you can see that's the case there that

110
00:12:52.080 --> 00:13:00.290
I've done that in the add song doc string on line 41 now if an argument is optional then its a good idea to describe

111
00:13:00.290 --> 00:13:03.800
what will happen if the arguments not
provided in this case the song is gonna

112
00:13:03.800 --> 00:13:06.000
be added to the end of the list

113
00:13:06.000 --> 00:13:10.420
the album class also uses a list to
store the songs and provides a method this

114
00:13:10.420 --> 00:13:15.060
add song method add_song for
adding songs to a list and in addition

115
00:13:15.060 --> 00:13:18.670
its got a filed for the artists which is a next
class and I'm gonna be adding to this

116
00:13:18.670 --> 00:13:22.960
program in the next video so having this
artist object stored in the album

117
00:13:22.960 --> 00:13:27.750
objects can cause problems I because the
artist class itself will also hold a list of

118
00:13:27.750 --> 00:13:30.130
the artist published albums

119
00:13:30.130 --> 00:13:34.830
but I'm gonna talk more about that when was seen the
artist class so lets end this video here now then

120
00:13:34.830 --> 00:13:37.200
will continue on with this project in the
next video