blob: 598859de6a56ad6bf2860ada82e9e14571a2f16b [file] [log] [blame]
Georg Brandl116aa622007-08-15 14:28:22 +00001.. _tut-brieftour:
2
3**********************************
4Brief Tour of the Standard Library
5**********************************
6
7
8.. _tut-os-interface:
9
10Operating System Interface
11==========================
12
13The :mod:`os` module provides dozens of functions for interacting with the
14operating system::
15
16 >>> import os
Georg Brandl116aa622007-08-15 14:28:22 +000017 >>> os.getcwd() # Return the current working directory
Yury Selivanov7aa53412015-05-30 10:57:56 -040018 'C:\\Python35'
Georg Brandlfe123902010-11-26 12:12:14 +000019 >>> os.chdir('/server/accesslogs') # Change current working directory
20 >>> os.system('mkdir today') # Run the command mkdir in the system shell
21 0
Georg Brandl116aa622007-08-15 14:28:22 +000022
23Be sure to use the ``import os`` style instead of ``from os import *``. This
Mark Dickinson934896d2009-02-21 20:59:32 +000024will keep :func:`os.open` from shadowing the built-in :func:`open` function which
Georg Brandl116aa622007-08-15 14:28:22 +000025operates much differently.
26
27.. index:: builtin: help
28
Mark Dickinson934896d2009-02-21 20:59:32 +000029The built-in :func:`dir` and :func:`help` functions are useful as interactive
Georg Brandl116aa622007-08-15 14:28:22 +000030aids for working with large modules like :mod:`os`::
31
32 >>> import os
33 >>> dir(os)
34 <returns a list of all module functions>
35 >>> help(os)
36 <returns an extensive manual page created from the module's docstrings>
37
38For daily file and directory management tasks, the :mod:`shutil` module provides
39a higher level interface that is easier to use::
40
41 >>> import shutil
42 >>> shutil.copyfile('data.db', 'archive.db')
Raymond Hettingerbd46e482014-05-22 23:37:09 +010043 'archive.db'
Georg Brandl116aa622007-08-15 14:28:22 +000044 >>> shutil.move('/build/executables', 'installdir')
Raymond Hettingerbd46e482014-05-22 23:37:09 +010045 'installdir'
Georg Brandl116aa622007-08-15 14:28:22 +000046
47
48.. _tut-file-wildcards:
49
50File Wildcards
51==============
52
53The :mod:`glob` module provides a function for making file lists from directory
54wildcard searches::
55
56 >>> import glob
57 >>> glob.glob('*.py')
58 ['primes.py', 'random.py', 'quote.py']
59
60
61.. _tut-command-line-arguments:
62
63Command Line Arguments
64======================
65
66Common utility scripts often need to process command line arguments. These
67arguments are stored in the :mod:`sys` module's *argv* attribute as a list. For
68instance the following output results from running ``python demo.py one two
69three`` at the command line::
70
71 >>> import sys
Guido van Rossum0616b792007-08-31 03:25:11 +000072 >>> print(sys.argv)
Georg Brandl116aa622007-08-15 14:28:22 +000073 ['demo.py', 'one', 'two', 'three']
74
75The :mod:`getopt` module processes *sys.argv* using the conventions of the Unix
76:func:`getopt` function. More powerful and flexible command line processing is
Steven Bethard6d265692010-03-02 09:22:57 +000077provided by the :mod:`argparse` module.
Georg Brandl116aa622007-08-15 14:28:22 +000078
79
80.. _tut-stderr:
81
82Error Output Redirection and Program Termination
83================================================
84
85The :mod:`sys` module also has attributes for *stdin*, *stdout*, and *stderr*.
86The latter is useful for emitting warnings and error messages to make them
87visible even when *stdout* has been redirected::
88
89 >>> sys.stderr.write('Warning, log file not found starting a new one\n')
90 Warning, log file not found starting a new one
91
92The most direct way to terminate a script is to use ``sys.exit()``.
93
94
95.. _tut-string-pattern-matching:
96
97String Pattern Matching
98=======================
99
100The :mod:`re` module provides regular expression tools for advanced string
101processing. For complex matching and manipulation, regular expressions offer
102succinct, optimized solutions::
103
104 >>> import re
105 >>> re.findall(r'\bf[a-z]*', 'which foot or hand fell fastest')
106 ['foot', 'fell', 'fastest']
107 >>> re.sub(r'(\b[a-z]+) \1', r'\1', 'cat in the the hat')
108 'cat in the hat'
109
110When only simple capabilities are needed, string methods are preferred because
111they are easier to read and debug::
112
113 >>> 'tea for too'.replace('too', 'two')
114 'tea for two'
115
116
117.. _tut-mathematics:
118
119Mathematics
120===========
121
122The :mod:`math` module gives access to the underlying C library functions for
123floating point math::
124
125 >>> import math
Georg Brandlf6945182008-02-01 11:56:49 +0000126 >>> math.cos(math.pi / 4)
Georg Brandl116aa622007-08-15 14:28:22 +0000127 0.70710678118654757
128 >>> math.log(1024, 2)
129 10.0
130
131The :mod:`random` module provides tools for making random selections::
132
133 >>> import random
134 >>> random.choice(['apple', 'pear', 'banana'])
135 'apple'
136 >>> random.sample(range(100), 10) # sampling without replacement
137 [30, 83, 16, 4, 8, 81, 41, 50, 18, 33]
138 >>> random.random() # random float
139 0.17970987693706186
140 >>> random.randrange(6) # random integer chosen from range(6)
Georg Brandl48310cd2009-01-03 21:18:54 +0000141 4
Georg Brandl116aa622007-08-15 14:28:22 +0000142
Guido van Rossum0616b792007-08-31 03:25:11 +0000143The SciPy project <http://scipy.org> has many other modules for numerical
144computations.
Georg Brandl116aa622007-08-15 14:28:22 +0000145
146.. _tut-internet-access:
147
148Internet Access
149===============
150
151There are a number of modules for accessing the internet and processing internet
Senthil Kumaranaca8fd72008-06-23 04:41:59 +0000152protocols. Two of the simplest are :mod:`urllib.request` for retrieving data
Ezio Melottic926c592012-09-24 17:07:39 +0300153from URLs and :mod:`smtplib` for sending mail::
Georg Brandl116aa622007-08-15 14:28:22 +0000154
Georg Brandl0f7ede42008-06-23 11:23:31 +0000155 >>> from urllib.request import urlopen
Berker Peksag9575e182015-04-12 13:52:49 +0300156 >>> with urlopen('http://tycho.usno.navy.mil/cgi-bin/timer.pl') as response:
157 ... for line in response:
158 ... line = line.decode('utf-8') # Decoding the binary data to text.
159 ... if 'EST' in line or 'EDT' in line: # look for Eastern Time
160 ... print(line)
Georg Brandl116aa622007-08-15 14:28:22 +0000161
162 <BR>Nov. 25, 09:43:32 PM EST
163
164 >>> import smtplib
165 >>> server = smtplib.SMTP('localhost')
166 >>> server.sendmail('soothsayer@example.org', 'jcaesar@example.org',
Guido van Rossumf10aa982007-08-17 18:30:38 +0000167 ... """To: jcaesar@example.org
168 ... From: soothsayer@example.org
169 ...
170 ... Beware the Ides of March.
171 ... """)
Georg Brandl116aa622007-08-15 14:28:22 +0000172 >>> server.quit()
173
Guido van Rossumf10aa982007-08-17 18:30:38 +0000174(Note that the second example needs a mailserver running on localhost.)
175
Georg Brandl116aa622007-08-15 14:28:22 +0000176
177.. _tut-dates-and-times:
178
179Dates and Times
180===============
181
182The :mod:`datetime` module supplies classes for manipulating dates and times in
183both simple and complex ways. While date and time arithmetic is supported, the
184focus of the implementation is on efficient member extraction for output
185formatting and manipulation. The module also supports objects that are timezone
186aware. ::
187
Ezio Melotti87e5d342009-11-12 10:38:55 +0000188 >>> # dates are easily constructed and formatted
Georg Brandl116aa622007-08-15 14:28:22 +0000189 >>> from datetime import date
190 >>> now = date.today()
191 >>> now
192 datetime.date(2003, 12, 2)
193 >>> now.strftime("%m-%d-%y. %d %b %Y is a %A on the %d day of %B.")
194 '12-02-03. 02 Dec 2003 is a Tuesday on the 02 day of December.'
195
Ezio Melotti87e5d342009-11-12 10:38:55 +0000196 >>> # dates support calendar arithmetic
Georg Brandl116aa622007-08-15 14:28:22 +0000197 >>> birthday = date(1964, 7, 31)
198 >>> age = now - birthday
199 >>> age.days
200 14368
201
202
203.. _tut-data-compression:
204
205Data Compression
206================
207
208Common data archiving and compression formats are directly supported by modules
Ezio Melotti0ada6f12012-10-26 19:33:07 +0300209including: :mod:`zlib`, :mod:`gzip`, :mod:`bz2`, :mod:`lzma`, :mod:`zipfile` and
Georg Brandl116aa622007-08-15 14:28:22 +0000210:mod:`tarfile`. ::
211
212 >>> import zlib
Georg Brandl53afa6d2010-11-30 08:20:16 +0000213 >>> s = b'witch which has which witches wrist watch'
Georg Brandl116aa622007-08-15 14:28:22 +0000214 >>> len(s)
215 41
216 >>> t = zlib.compress(s)
217 >>> len(t)
218 37
219 >>> zlib.decompress(t)
Georg Brandl53afa6d2010-11-30 08:20:16 +0000220 b'witch which has which witches wrist watch'
Georg Brandl116aa622007-08-15 14:28:22 +0000221 >>> zlib.crc32(s)
222 226805979
223
224
225.. _tut-performance-measurement:
226
227Performance Measurement
228=======================
229
230Some Python users develop a deep interest in knowing the relative performance of
231different approaches to the same problem. Python provides a measurement tool
232that answers those questions immediately.
233
234For example, it may be tempting to use the tuple packing and unpacking feature
235instead of the traditional approach to swapping arguments. The :mod:`timeit`
236module quickly demonstrates a modest performance advantage::
237
238 >>> from timeit import Timer
239 >>> Timer('t=a; a=b; b=t', 'a=1; b=2').timeit()
240 0.57535828626024577
241 >>> Timer('a,b = b,a', 'a=1; b=2').timeit()
242 0.54962537085770791
243
244In contrast to :mod:`timeit`'s fine level of granularity, the :mod:`profile` and
245:mod:`pstats` modules provide tools for identifying time critical sections in
246larger blocks of code.
247
248
249.. _tut-quality-control:
250
251Quality Control
252===============
253
254One approach for developing high quality software is to write tests for each
255function as it is developed and to run those tests frequently during the
256development process.
257
258The :mod:`doctest` module provides a tool for scanning a module and validating
259tests embedded in a program's docstrings. Test construction is as simple as
260cutting-and-pasting a typical call along with its results into the docstring.
261This improves the documentation by providing the user with an example and it
262allows the doctest module to make sure the code remains true to the
263documentation::
264
265 def average(values):
266 """Computes the arithmetic mean of a list of numbers.
267
Guido van Rossum0616b792007-08-31 03:25:11 +0000268 >>> print(average([20, 30, 70]))
Georg Brandl116aa622007-08-15 14:28:22 +0000269 40.0
270 """
Georg Brandlf6945182008-02-01 11:56:49 +0000271 return sum(values) / len(values)
Georg Brandl116aa622007-08-15 14:28:22 +0000272
273 import doctest
274 doctest.testmod() # automatically validate the embedded tests
275
276The :mod:`unittest` module is not as effortless as the :mod:`doctest` module,
277but it allows a more comprehensive set of tests to be maintained in a separate
278file::
279
280 import unittest
281
282 class TestStatisticalFunctions(unittest.TestCase):
283
284 def test_average(self):
285 self.assertEqual(average([20, 30, 70]), 40.0)
286 self.assertEqual(round(average([1, 5, 7]), 1), 4.3)
Raymond Hettinger8f35c892013-03-22 07:26:18 -0700287 with self.assertRaises(ZeroDivisionError):
288 average([])
289 with self.assertRaises(TypeError):
290 average(20, 30, 70)
Georg Brandl116aa622007-08-15 14:28:22 +0000291
292 unittest.main() # Calling from the command line invokes all tests
293
294
295.. _tut-batteries-included:
296
297Batteries Included
298==================
299
300Python has a "batteries included" philosophy. This is best seen through the
301sophisticated and robust capabilities of its larger packages. For example:
302
Georg Brandl38eceaa2008-05-26 11:14:17 +0000303* The :mod:`xmlrpc.client` and :mod:`xmlrpc.server` modules make implementing
Georg Brandl116aa622007-08-15 14:28:22 +0000304 remote procedure calls into an almost trivial task. Despite the modules
305 names, no direct knowledge or handling of XML is needed.
306
307* The :mod:`email` package is a library for managing email messages, including
308 MIME and other RFC 2822-based message documents. Unlike :mod:`smtplib` and
309 :mod:`poplib` which actually send and receive messages, the email package has
310 a complete toolset for building or decoding complex message structures
311 (including attachments) and for implementing internet encoding and header
312 protocols.
313
314* The :mod:`xml.dom` and :mod:`xml.sax` packages provide robust support for
315 parsing this popular data interchange format. Likewise, the :mod:`csv` module
316 supports direct reads and writes in a common database format. Together, these
Ezio Melotti0639d5a2009-12-19 23:26:38 +0000317 modules and packages greatly simplify data interchange between Python
Georg Brandl116aa622007-08-15 14:28:22 +0000318 applications and other tools.
319
320* Internationalization is supported by a number of modules including
321 :mod:`gettext`, :mod:`locale`, and the :mod:`codecs` package.
322
323