Chapter 8 Modules and Packages

Functions for Bookkeeping

seed(a = None, version = 2)

This initializes the random number generator by seeding the generator. If there is no argument for a, the current time is used to seed the generator. Version 2 is the default version of the algorithm.

getstate()

This gets and returns the current internal state of the random number generator.

setstate(state)

This sets the internal state of the random number generator to state.

getrandbits(k)

This generates and returns an integer with k random bits.

Functions for Generating Random Integers

randrange(start, stop=None, step = 1)

This generates and returns a random number within the given range.

randint(a, b)

This generates and returns a random integer within the given range.

Functions for Randomly Generating Float Numbers

random()

This randomly generates and returns a random float number between 0 and 1, including 0 but excluding 1.

uniform(a, b)

This randomly generates and returns a float number between a and b.

triangular(low = 0.0, high = 1.0, mode = None)

This randomly generates and returns a random float number between low and high. The third argument for mode parameter can be used to indicate the preference for the outcome. If it is closer to low, it is more likely to get a random float number on the low end, for example. Internally, the default value for mode is the midpoint between low and high.

betavariate(alpha, beta)

This randomly generates and returns a random float number between 0 and 1 based on the beta distribution of statistics. Parameters alpha and beta (both > 0) are used to set the conditions of the distribution, as used in the beta distribution function.

expovariate(lambda)

This randomly generates and returns a random float number between 0 and 1, or between 0 and −1 if lambda is negative, based on the exponential distribution of statistics.

gammavariate(alpha, beta)

This randomly generates and returns a random float number between 0 and 1 based on the gamma distribution of statistics. Parameters alpha and beta (both > 0) are used to set the conditions of the distribution, as used in the gamma distribution function.

gauss(mu, sigma)

This randomly generates and returns a random float number between 0 and 1 based on the Gaussian distribution of probability theories. Parameter mu is the mean, and sigma is the standard deviation, as used in the distribution function.

lognormvariate(mu, sigma)

This generates and returns a random float number between 0 and 1 based on a log-normal distribution of probability theories. Parameter mu is the mean, and sigma is the standard deviation, as used in the log normal distribution function.

normalvariate(mu, sigma)

This generates and returns a random float number between 0 and 1 based on the normal distribution of probability theories. Parameter mu is the mean, and sigma is the standard deviation, as used in the normal distribution function.

vonmisesvariate(mu, kappa)

This generates and returns a random float number between 0 and 1 based on the von Mises distribution of directional statistics. Parameter mu is the mean angle, expressed in radians between 0 and 2 * pi, whereas kappa is the concentration.

paretovariate(alpha)

This generates and returns a random float number between 0 and 1 based on the Pareto distribution of probability theories. Parameter alpha is used to indicate the shape.

weibullvariate(alpha,beta)

This generates and returns a random float number between 0 and 1 based on the Weibull distribution of statistics. Parameter alpha is the scale, and beta is the shape, as in its mathematical function.

Functions for Randomly Selected Item(s) from Sequences

Functions in this group are often used in statistics.

choice(population)

This generates and returns a random element from the given population (in the form of a Python sequence).

choices(population, weights = None, *, cum_weights = None, k = 1)

This generates and returns a list with k randomly selected items from the given sequence, with weights or cumulative weights considered if they are given. An optional argument for weights should be a list of integers specifying how likely the corresponding items are to be selected. The number of integers in weights must match the number of items in the population; optional argument for cum_weights is also a list. A value in the list is shown as cumulation of weights so far. Argument weights and cum_weights are just different ways of representing the same preferences.

This function can be very useful when you want to generate a quiz by randomly selecting questions from a question bank. Assume the question bank is called q_bank, and each quiz will have 10 questions. The random choices can be easily made by calling the function as follows:

shuffle(population, random = None)

This takes a sequence, shuffles the members, then returns the sequence with the members randomly shuffled.

sample(population, k)

This generates and returns a sample for a given population. It seems similar to choices(), but internally the algorithm should check whether the choices would make a sample of the population according to some sampling criteria in statistics.

In the following programming problem in Table 8-1, you will study how well the random generator works. You will randomly generate 1000 integer numbers within the range of 0 to 999 and visualize the randomness of these numbers.

The Datetime Module

The first of these modules is the datetime module that comes in the standard Python library. To use the module, simply import it as shown below:

To find out what is defined and available in the module, run the following dir statement:

To further find out what each name is defined for, use the help statement on each. As usual, we will go through some of the important names defined in the module, with examples.

datetime.date(<year, month, day>)

This is the constructor of the date class defined in the datetime module and used to construct and return a date object for the day of the month of the year.

A date object has the following methods defined.

datetime.date.ctime()

This returns a ctime()-style string.

datetime.date.isocalendar()

This returns a three-tuple containing an ISO year, week number of the year, and day number of the week. In the datetime module, Monday is 1, Tuesday is 2,…, Sunday is 7.

datetime.date.isoformat()

This returns a date string in ISO 8601 format, YYYY-MM-DD.

datetime.date.isoweekday()

This returns an integer from 1 to 7 as the day of the week represented by the date.

datetime.date.replace(…)

This returns the date with new specified fields.

datetime.date.strftime(…)

This changes the date format and returns a strftime()-style string.

datetime.date.timetuple(…)

This returns a time-tuple that is compatible with time.localtime().

datetime.date.toordinal(…)

This returns a proleptic Gregorian ordinal. January 1 of year 1 is day 1.

datetime.date.weekday(…)

This returns the day of the week represented by the date: Monday is 0…Sunday is 6.

The following are all class methods of the date class defined in the datetime module, which means they can be called from the class name date.

datetime.date.fromisoformat(<ISO_date_format string>)

This will construct a date object from an ISO date format string, which is YYYY-MM-DD.

datetime.date.fromordinal(<days in relation to a proleptic Gregorian ordinal>)

This constructs a date object from an integer >= 1 representing the days after the proleptic Gregorian ordinal, which is January 1 of year 1, with ordinal 1.

datetime.date.fromtimestamp(<timestamp>)

This constructs a local date object from a POSIX timestamp (a big positive float number), such as returned time.time(), which will be explained shortly.

datetime.date.today()

This returns a date object of for the current date.

The datetime module also has a class called time. The following is the constructor of the time class.

datetime.time(hour = 0, minute = 0, second = 0, microsecond = 0, tzinfo = None)

This returns a time object. All arguments with 0 as their default value must be in their reasonable range or the program will raise a value error. If no argument is provided, they are all 0, except tzinfo (for time zone information, which needs to be an instance of tzinfo class if given). The default value of tzinfo is None.

The following is the only class method of the date class in the datetime module.

time.fromisoformat(…)

This class method will construct a date object from a string passed in the parameter.

The datetime module also has a class called datetime, which is a combination of date and time. The following is the constructor of the datetime objects.

datetime.datetime(year, month, day, hour = 0, minute = 0, second = 0, microsecond = 0, tzinfo = None, *, fold = 0)

This returns a datetime object for the date and time given in the arguments. If no time is given, the default is the beginning of the day of the month of the year.

The following are the methods defined in the datetime class.

datetime.ctime(…)

This returns a ctime()-style time string.

datetime.astimezone(tz)

This converts to the local time with the time zone set to <tz> or local.

A complete list of time zone names can be found at https://en.wikipedia.org/wiki/List_of_tz_database_time_zones.

datetime.date()

This returns a date object of the date portion of the datetime object with the same year, month, and day.

datetime.dst()

This returns the DST (daylight saving time) status of a given tzinfo.

datetime.isoformat(sep = 'T')

This returns a date and time string in ISO 8601 format, YYYY-MM-DDT[HH[:MM[:SS[.mmm[uuu]]]]][+HH:MM]. sep is a single character used to separate the year from the time, and defaults to T. timespec specifies what components of the time to include. The allowed values include the following: auto, hours, minutes, seconds, milliseconds, and microseconds.

datetime.replace(<field>=<value>)

This returns a datetime object with the named field(s) replaced.

datetime.time()

This returns a time object for the time portion of the datetime object but with tzinfo = None.

datetime.timestamp()

This returns POSIX timestamp as a float number.

datetime.timetuple()

This returns a time-tuple compatible with time.localtime().

datetime.timetz()

This returns a time object with the same time and tzinfo. Note the difference between timetz() and time().

datetime.tzname(…)

This returns the tzname of tzinfo.

datetime.utcoffset(…)

This returns utcoffset of tzinfo.

The following are some class methods defined in the datetime class.

datetime.combine(dt, tm)

This combines the date dt and time tm into a datetime object and returns the datetime object.

datetime.fromisoformat(dtmstr)

This constructs the datetime object from a date and time string in ISO format and returns the converted datetimeobject. Remember that the ISO time string format is YYYY-MM-DDTHH:MM:SS:mmm:uuu.

datetime.fromtimestamp(…)

This constructs a datetime object from a POSIX timestamp.

datetime.now(tz = None)

This returns a datetime object representing the current time local to tz, which should be a Timezone object if given. If no tz is specified, the local timezone is used.

datetime.strptime(<date_string, format>)

This returns a datetime object by parsing a date_string, based on a given format.

datetime.today()

This returns a datetime object for today.

datetime.utcfromtimestamp()

This constructs a naive UTC datetime from a POSIX timestamp.

datetime.utcnow()

This returns a new datetime representing the UTC day and time.

Sometimes, you need to deal with time intervals such as how long has passed since the last time you saw your best friend. That is what the timedelta class is defined for in the datetime module. The following is the constructor of the class.

datetime.timedelta(days = 0, seconds = 0, microseconds = 0, milliseconds = 0, minutes = 0, hours = 0, weeks = 0)

This constructs and returns a timedelta object. Note that all arguments are optional, and all default to 0 if not provided.

timedelta.total_seconds(…)

This returns the total number of seconds in the duration.

The Time Module

The second of these modules is the time module. It comes with the standard Python distribution, so there is no need for you to install anything in particular. This module can be imported and used directly within your program when needed. The following statements get us a list of the names defined in the module:

In the following, we explain the names, including attributes and functions, available in the time module on a Windows platform. The code samples are all shown as they would appear in a Python interactive shell. If you wish to see all functions defined in the time module, please read the documentation at https://docs.python.org/3/library/time.html.

time.altzone

This is an attribute that contains the offset of the local DST timezone in seconds west of UTC, if one is defined. The value is negative if the local DST timezone is east of UTC (as in Western Europe, including the UK). Only use this if daylight is nonzero.

time.asctime(tupletime)

This accepts a time-tuple and returns a readable 24-character string such as Tue Dec 11 18:07:14 2008. A time-tuple has nine elements, as returned by gmtime() or localtime().

time.clock()

This returns a floating-point number for the CPU time or real time since the start of the process or since the first call to clock(). It is very useful, especially when measuring the computational cost of a code block.

time.ctime([secs])

This returns a time in seconds since the epoch to a string in the local time. Remember that the argument in [] is optional.

This has the same result as asctime(localtime(secs)), and simply a call of asctime(), which will use the current local time in seconds.

time.get_clock_info(name)

This returns information on the specified clock as a namespace object. Supported clock names and the corresponding functions to read their value are the following: monotonic, perf_counter, process_time, thread_time, and time.

time.gmtime([secs])

This accepts an instant expressed in seconds since the epoch and returns a time-tuple t with the UTC time. Note: t.tm_isdst is always 0.

time.localtime([secs])

This accepts an instant expressed in seconds since the epoch and returns a time-tuple t with the local time (t.tm_isdst is 0 or 1, depending on whether DST applies to instant secs by local rules).

time.mktime(tupletime)

This accepts a time instant expressed as a time-tuple in the local time and returns a floating-point value, with the instant expressed in seconds since the epoch.

time.monotonic()

This returns the value of a monotonic clock as a float number, the number of seconds since the previous call. The clock is not affected by system clock updates. The reference point of the returned value is undefined, so that only the difference between the results of consecutive calls is valid.

time.monotonic_ns()

This is similar to monotonic() but returns time as nanoseconds.

time.perf_counter()

This returns the value of a performance counter as a float number since the previous call. A performance counter is a clock with the highest available resolution to measure a short duration. It includes time elapsed during sleep and is system-wide. The reference point of the returned value is undefined, so that only the difference between the results of consecutive calls is valid.

time.perf_counter_ns()

This is similar to perf_counter() but returns time as nanoseconds.

time.process_time()

This returns the value (in fractional seconds) of the sum of the system and the user CPU time of the current process. It does not include time elapsed during sleep. It is process-wide by definition. The reference point of the returned value is undefined so that only the difference between the results of consecutive calls is valid.

time.process_time_ns()

This is similar to process_time() but returns time as nanoseconds.

time.sleep(secs)

This suspends the calling thread for secs (seconds). It can be used to delay programs.

time.strftime(fmt[,tupletime])

This accepts an instant expressed as a time-tuple in the local time and returns a string representing the instant as specified by string fmt.

time.strptime(stringtime[, fmt])

This parses str according to format string fmt and returns the instant in time-tuple format.

time.time()

This returns the current time instant, a floating-point number of seconds since the epoch.

The Calendar Module

If you prefer a simple and more direct module to handle time and date, you can use the calendar module, as detailed below.

calendar.calendar(year, w = 2, l = 1, c = 6)

This returns a formatted calendar for year—a multiline string formatted into three columns separated by c spaces. w is the width in characters of each date; each line has length 21 * w + 18 + 2 * c. l is the number of lines for each week.

calendar.firstweekday()

This returns an integer that is the current setting for the weekday that starts each week. By default, when the calendar module is first imported, it is 0 for Monday.

calendar.isleap(year)

This tests if a year is a leap year. It returns True if it is; it returns False otherwise.

calendar.leapdays(y1, y2)

This returns the total number of leap days in the years within range(y1, y2).

calendar.month(year, month, w = 2, l = 1)

This returns a multiline string with a calendar for month of year, one line per week plus two header lines. w is the width in characters of each date; each line has length 7 * w + 6. l is the number of lines for each week.

calendar.monthcalendar(year, month)

This returns a list of sublists of integers. Each sublist denotes a week starting from Monday. Days outside month of year are set to 0; days within the month are set to their day-of-month, 1 and up. The result as a list of sublists can be conveniently used in applications. For example, you can easily tell what date it is for Monday of the third week of a month.

calendar.monthrange(year, month)

This returns two integers. The first one is the code of the weekday for the first day of the month in year; the second one is the number of days in the month. Weekday codes are 0 (Monday) to 6 (Sunday); month numbers are 1 (January) to 12 (December). This is useful if you want to print a calendar that begins on a specific day of the week.

calendar.prcal(year, w = 2, l = 1, c = 6)

This prints a well-formatted calendar of a given year. It is the same as calendar.calendar(year, w, l, c). Remember that w is the width of each date in number of characters and l is the number of lines for each week.

calendar.prmonth(year, month, w = 2, l = 1)

This prints a well-formatted calendar month, the same as the one created by calendar.month(year, month, w, l).

calendar.setfirstweekday(weekday)

This sets the first day of each week. Weekday codes are 0 (Monday by default) to 6 (Sunday by default), so if you change this, you will see the days in the calendar shift.

calendar.timegm(tupletime)

This is the inverse of time.gmtime. It accepts a time instant in time-tuple form and returns the same instant as a floating-point number of seconds since the epoch.

calendar.weekday(year, month, day)

This returns the weekday code for the given date. Weekday codes are 0 (Monday) to 6 (Sunday); month numbers are 1 (January) to 12 (December).

Our last example in Jupyter Lab is to display a calendar for March of 1961.

With the calendar module, you will be able to produce a calendar of any year you want.

OS Module for Interacting with the Operating System

Since it is a built-in module, all you need to do to use the os module is import it, as shown below:

If you use the dir(os) statement, you can get a rather big list of names defined in the module. Note that because the os module is operating-system dependent, you may get a different list of names available depending on your platform (e.g., Windows or Linux).

The following are some functions provided in the os module. You are encouraged to test these functions with your own examples on your own machine.

os.access(path, mode)

This tests if access to path is in mode, which is an integer such as 777 (111111111) representing the global, group, and user’s executable, write, and read rights.

os.chdir(path)

This changes the current working directory to path.

os.chmod(path, mode)

This changes the mode of path to the numeric mode.

os.chown(path, uid, gid)

This changes the owner and group id of path to the numeric uid and gid. Please note that these operations are more similar to what you would do on a Unix/Linux system, all subject to permission by the operating system.

os.close(fd)

This closes the file descriptor fd. A file descriptor is returned by the os.open() function.

os.cpu_count()

This returns the number of CPUs in the system; it will return None if the number is indeterminable.

os.get_exec_path(env=None)

This returns the sequence of directories that will be searched for by the named executable.

os.getcwd()

This returns a Unicode string representing the current working directory.

os.getcwdb()

This returns a byte string representing the current working directory.

os.getenv(key, default=None)

This returns an environment variable and returns None if it does not exist. The optional second argument can specify an alternate default.

os.getlogin()

This returns the actual login name.

os.link(src, dst)

This creates a hard link pointing to src named dst.

os.listdir(path)

This returns a list containing the names of the entries in the directory given by path.

os.mkdir(path, mode=511, dir_fd=None)

This function is used to create a directory, the mode argument only used on Unix-like systems, and will be ignored on Windows. The path argument is required; the mode argument is optional and takes an integer representing permission for the path to be created. Argument _dir_fd is a file descriptor referring to a directory that the new directory will be under; the path is not an absolute path. The default value is None.

os.makedirs(path, mode = 511, exist_ok = False)

This recursively makes directories. For example, if the path is ./comp218/assignment1, it will first make a directory named comp218 under the current working directory, if it doesn’t exist, then make assignment1 under comp218. The optional mode argument is the same as the one in os.mkdir(). The optional exist_ok argument tells if the operation will continue if the leaf directory already exists. The default is False, meaning that a FileExistsError will be raised if the leaf directory already exists.

os.open(path, flags, mode = 511, *, dir_fd = None)

This opens the file path and sets various flags for low-level IO and returns a file descriptor to be used by other functions in the os module. Argument dir_fd should be a file descriptor open to a directory (if not default None) and can be used to provide a directory that the file path is relative to. The flags argument tells what the path is opened for. It can take one or some of the following values joined with or |: os.O_RDONLY, os.O_WRONLY, os.O_RDWR, os.O_APPEND, os.O_CREAT, os.O_EXCL¶, os.O_TRUNC. These values are available on both Windows and Unix platforms.

os.putenv(name, value)

This changes or adds an environment variable if name doesn’t exist yet.

os.read(fd, n)

This reads at most n bytes from file descriptor fd and returns a string containing the bytes read. If the end of the file referred to by fd has been reached, an empty string is returned.

os.umask(mask)

This sets the current numeric umask to mask and returns the previous umask. umask is used by operating systems to determine the default permission for newly created files.

os.urandom(size)

This returns a bytes object containing random bytes suitable for cryptographic use.

os.utime(path, times = None)

This sets the access and modified times of path, such as on a file.

os.walk(top)

This is a directory-tree generator and returns a walk object. For each directory in the directory tree rooted at top, it will yield a three-tuple (dirpath, dirnames, filenames), in which dirpath is a string, the path to the directory; dirnames is a list of the names of the subdirectories in dirpath; and filenames is a list of the names of the nondirectory files in dirpath.

Note that the names in the lists are just names, with no path components. To get a full path (which begins with top) to a file or directory in dirpath, use os.path.join(dirpath, name).

os.walk(top, topdown = True, onerror = None, followlinks = False)

This generates the file names in a directory tree by walking the tree either from the top down or from the bottom up. The os.walk function will be very useful in completing one of the projects in the textbook.

os.write(fd, str)

This writes the string str to the file descriptor fd and returns the number of bytes actually written.

The path Submodule from os for Manipulating File Paths

When dealing with files and file systems, we quite often need to manipulate file paths. For that reason, the os module has a submodule called path. To use the path module, run the following statement:

The path module provides functions for joining and splitting paths, getting information about a path or file such as its size and timestamp, and testing whether a path is a file, a directory, a real path, or just a link.

path.abspath(p)

This returns the absolute version of p.

path.basename(p)

This returns the final component of a pathname.

path.commonpath(paths)

This returns the longest common subpath for a given sequence of pathnames.

path.commonprefix(paths)

This returns the longest common leading component of a given list of pathnames.

path.dirname(p)

This returns the directory component of a pathname.

path.exists(p)

This tests whether a path exists. It returns False for broken symbolic links.

path.expanduser(p)

This expands ~ and ~user constructs, mostly for Unix/Linux systems. If user or $HOME is unknown, it does nothing.

path.expandvars(p)

This expands shell variables of the forms $var, ${var}, and %var%. Unknown variables will be left unchanged.

path.getatime(filename)

This returns the time a file was last accessed, as reported by os.stat().

path.getctime(filename)

This returns the time a file’s metadata was last changed, as reported by os.stat().

path.getmtime(filename)

This returns the time a file was last modified, as reported by os.stat().

path.getsize(filename)

This returns the size of a file, as reported by os.stat().

path.isabs(s)

This tests whether a path is absolute.

path.isdir(p)

path._isdir(p)

These return True if the pathname refers to an existing directory.

path.isfile(p)

This tests whether a path is a regular file.

path.islink(p)

This tests whether a path is a symbolic link. It will always return False for Windows prior to 6.0.

path.ismount(p)

This tests whether a path is a mount point (a drive root, the root of a share, or a mounted volume).

path.join(p1, p2)

This is used to join two paths or a path with a file.

path.lexists(p)

This tests whether a path exists. It will return True for broken symbolic links.

path.normcase(s)

This normalizes the case of a pathname. That is, it makes all characters lower case and all slashes backslashes.

path.normpath(p)

This normalizes the path, eliminating double slashes, etc.

path.abspath(p)

This returns the absolute version of a path.

path.relpath(p, start=None)

This returns a relative version of a path.

path.samefile(f1, f2)

This tests whether two pathnames reference the same actual file or directory.

path.sameopenfile(fp1, fp2)

This tests whether two open file objects reference the same file.

path.samestat(s1, s2)

This tests whether two stat buffers reference the same file.

path.split(p)

This splits a pathname and returns tuple (head, tail), where tail is everything after the final slash.

path.splitdrive(p)

This splits a pathname into a drive/UNC sharepoint and relative path specifiers and returns a two-tuple (drive_or_unc, path); either part may be empty.

path.splitext(p)

This splits the extension from a pathname. An extension is everything from the last dot to the end, ignoring leading dots. For some paths without a dot, the extension part will be empty.

The sys Module for Interaction Between the Python and Python Interpreter or Python Virtual Machine (PVM)

The os and path modules we studied above provide programmers with ways to interact with the operating system and to access the underlying interface of the operating system. The sys module we are going to study below allows programs to interact with Python interpreter.

The following are the objects defined in the sys module and maintained by Python interpreter. These objects are put into two groups: dynamic objects and static objects.

The following are the dynamic objects defined in the sys module. Dynamic means the values can be changed.

sys.argv

This holds command-line arguments; argv[0] is the script pathname if known. The following example shows what happens when we test it in Jupyter Lab:

sys.path

This holds the module search path; path[0] is the script directory. The sys.path for the above Python program/script will be

sys.modules

This is a dictionary of all loaded modules. It will provide a long list of modules it is using.

sys.displayhook

This contains an executable object and can be called to show the results in an interactive session.

sys.excepthook

This contains an executable object and can be called to handle any uncaught exception other than SystemExit.

sys.stdin

This contains the standard input file object; it is used by input().

sys.stdout

It contains the standard output file object; it is used by print().

sys.stderr

This contains the standard error object; it is used for error messages.

sys.last_type

This contains the type of the last uncaught exception.

sys.last_value

This contains the value of the last uncaught exception.

sys.last_traceback

This contains the traceback of the last uncaught exception.

The above three objects are only available in an interactive session after a traceback has been printed.

The next group of objects available from the sys module are called static objects, which means the values do not change for the given Python interpreter being used.

sys.builtin_module_names

This contains a tuple of built-in module names.

sys.copyright

This contains the copyright notice pertaining to the interpreter in use. sys.copyright in our case will produce the following, as an example:

sys.exec_prefix

This contains the prefix used to find the machine-specific Python library.

sys.executable

This contains the absolute path of the executable binary of the Python interpreter.

sys.float_info

This contains a named tuple with information about the float implementation.

sys.float_repr_style

This contains a string indicating the style of repr() output for floats.

sys.hash_info

This contains a named tuple with information about the hash algorithm.

sys.hexversion

This contains version information encoded as a single integer.

sys.implementation

This contains Python implementation information.

sys.int_info

This contains a named tuple with information about the int implementation.

sys.maxsize

This contains the largest supported length of containers.

sys.maxunicode

This contains the value of the largest Unicode code point.

sys.platform

This contains the platform identifier.

sys.prefix

This contains the prefix used to find the Python library.

sys.thread_info

This contains a named tuple with information about the thread implementation.

sys.version

This contains the version of this interpreter as a string.

sys.version_info

This contains the version information as a named tuple.

sys.dllhandle

This is the integer handle of the Python DLL (Windows only).

sys.winver

This contains the version number of the Python DLL (Windows only).

sys.__stdin__

This is the original stdin.

sys.__stdout__

This is the original stdout.

sys.__stderr__

This is the original stderr.

sys.__displayhook__

This is the original displayhook.

sys.__excepthook__

This is the original excepthook.

The following are functions also defined in the sys module.

sys.displayhook()

This function prints an object to the screen and saves it in builtins.

sys.excepthook()

This function prints an exception and its traceback to sys.stderr.

sys.exc_info()

This function returns thread-safe information about the current exception.

sys.exit()

This function exits the interpreter by raising SystemExit.

sys.getdlopenflags()

This function returns flags to be used for dlopen() calls.

sys.getprofile()

This function returns the global profiling function.

sys.getrefcount()

This function returns the reference count for an object.

sys.getrecursionlimit()

This function returns the max recursion depth for the interpreter.

sys.getsizeof()

This function returns the size of an object in bytes.

sys.gettrace()

This function gets the global debug tracing function.

sys.setcheckinterval()

This function controls how often the interpreter checks for events.

sys.setdlopenflags()

This function sets the flags to be used for dlopen() calls.

sys.setprofile()

This function sets the global profiling function.

sys.setrecursionlimit()

This function sets the max recursion depth for the interpreter.

sys.settrace()

This function sets the global debug tracing function.

As can be seen, the sys module gives programmers a way to find out information about the Python interpreter and the runtime environment in particular.

winsound

To play WAV files in your Windows applications, you can use the winsound module included in the standard Python distribution. You can import the module and use the functions defined in it without installing the module. Using the following statements, you can get a list of names defined in the module:

For more details about the module and functionalities provided, run help(winsound) in Python interactive mode, as shown below:

Among the functions defined in the module, PlaySound is an important one for playing sound or music files. The following statement will play a WAV file named dj.wav.

When using the PlaySound function to a play sound file, you must make sure the WAV file exists in the default or specified path. In the example above, an absolute path has been given. You can also use a relative path that makes use of two special notations, a single dot (.) representing the current directory and a double dot (..) representing the parent directory; or you don’t need to specify the path at all if the WAV file is in the current directory. In any case, the rule is that you must be clearly aware of where the file is located. This rule is applicable whenever the file is used.

PyGame

The PlaySound function in the standard winsound module can play only WAV files. To play the popular MP3 music files in your Python applications, use the module called mixer in the PyGame package. Because the package is usually included in the standard Python distribution, you can install the package into your Python programming environment using the pip command, as shown below:

Then you can import and use the mixer module to load and play MP3 files, as shown below:

To learn more about how to use the mixer and mixer.music module, you can run the following commands in Python interactive mode as shown below, after the module has been imported:

You can then see the functions defined within the module, as further detailed below.

Channel(id)

This is used to create and return a Channel object for controlling playback.

fadeout(time)

This sets the time to fade out the volume on all sounds before stopping.

find_channel(force = False)

This finds and returns an unused channel.

get_busy()

This tests if any sound is being mixed and returns a Boolean value.

get_init()

This tests if the mixer is initialized and returns a tuple (frequency, format, channels) representing the channel.

get_num_channels()

This can be used to check and return the total number of playback channels.

init(frequency = 22050, size = −16, channels = 2, buffer = 4096, devicename = None, allowedchanges = AUDIO_ALLOW_FREQUENCY_CHANGE | AUDIO_ALLOW_CHANNELS_CHANGE)

This can be used to initialize the mixer module.

pause() -> None, temporarily stop playback of all sound channels

pre_init(frequency=22050, size = −16, channels = 2, buffersize = 4096, devicename = None)

These can be used to preset the mixer init arguments.

quit()

This can be used to uninitialize the mixer.

set_num_channels(count)

This can be used to set the total number of playback channels.

set_reserved(count)

This can be used to keep channels from being automatically used.

stop()

This can be used to stop playback on all sound channels.

unpause()

This can be used to resume playback on sound channels after it has been paused.

The mixer module has a submodule named music. To learn what functions are available in the mixer.music submodule module, run the following statement:

You will then see the following information about the related functions.

fadeout(time)

This can be used to stop music playback after fading out.

get_busy()

This can be used to check if the music stream is playing. It will return True or False.

get_endevent()

This can be used to get the event a channel sends when playback stops.

get_pos()

This can be used to get the music playtime.

get_volume() -> value

This can be used to get the music volume.

load(filename) -> None, or load(object) -> None,

This can be used to load a music file/object for playback.

pause() -> None

This can be used to temporarily stop music playback.

play(loops = 0, start = 0.0) -> None

This can be used to start the music stream playback.

queue(filename) -> None

This can be used to queue a music file to follow the currently playing file.

rewind() -> None

This can be used to restart the music.

set_endevent() -> None

set_endevent(type) -> None

These can be used to have the mixer send events when playback stops.

set_pos(pos) -> None

This can be used to set the position in the music file when starting playback.

set_volume(value) -> None

This can be used to set the music volume.

stop() -> None

This can be used to stop the music playback.

unpause() -> None

This can be used to resume paused music.

These functions in mixer.music are the ones used directly to handle music files. These functions are sufficient for you to develop a high-quality music player with what you will learn in Chapter 9 on developing GUI-based applications in Python.

Please note that the mixer module from the PyGame package can also play other types of music files including WAV, as shown below:

The functions listed above are needed if you are developing a music player with PyGame. For details on these functions, please refer to the official documentation on the PyGame mixer at https://www.pygame.org/docs/ref/mixer.html.

Create Graphics with Tkinter

The module built into the standard Python distribution for creating graphics is the Tkinter module, which is commonly used to develop graphical user interface (GUI) applications. However, Tkinter also provides a widget called Canvas for graphics and images. The following statements in Python interactive mode will produce a window containing a Canvas ready for drawing graphic objects—Canvas items:

Table 8-4 is a list of Canvas items we can draw on a Canvas.

Every method listed in Table 8-4 returns a unique ID for the created graphic object, which can be used later to manipulate the object.

Note that graphic objects created by the above methods will be stacked on the Canvas and will remain until being moved, lifted, lowered, or deleted, with the methods in Table 8-5.

Canvas has many other methods for accessing and manipulating graphic objects. Running the following statements in Python interactive mode will give you a list of names defined within the Canvas class.

You can then call help on each of the names in the list to learn more about the name defined. The following are just two examples:

Running help on the function addtag in module tkinter outputs the following:

• addtag(self, *args)
•     Internal function.

Running help on the function after in module tkinter outputs the following:

• after(self, ms, func=None, *args)
•     Call function once after given time.
•     MS specifies the time in milliseconds. FUNC gives the
•     function, which shall be called. Additional parameters
•     are given as parameters to the function call. Returns
•     identifier to cancel scheduling with after_cancel.

Running help on the function create_image in module tkinter outputs the following:

• create_image(self, *args, **kw)
•     Create image item with coordinates x1, y1.

The following coding example will draw a line on a Canvas:

Manipulate Images with Pillow

Another way you can work with visual objects in Python is to manipulate images stored in files. These manipulations include the following:

• • rotating
• • converting from colour to grey-scale
• • applying colour filtering
• • highlighting a specific area of an image
• • blurring an image or part of it
• • sharpening an image or part of it
• • changing the brightness of an image
• • detecting the edge on an image
• • scaling an image
• • applying colour inversion to an image
• • morphing one image into another image

How can all these manipulations be done within your computer? First, an image is made of pixels, which can be stored in an m × n matrix, or two-dimensional array, mapped to a rectangular area of the computer screen. The value of each cell of the matrix represents a pixel and contains all the information about it. All manipulations to the image can be done by manipulating the matrix or its values.

To manipulate an image with Python, you can use a package called Pillow (available from https://pypi.org/project/Pillow/2.2.1/ or https://github.com/python-pillow/Pillow). Because it is not a standard part of the Python library, you will need to install it with the following statement:

• pip install Pillow
• Collecting Pillow
• Downloading
• wordhttps://files.pythonhosted.org/packages/70/21/04723e78916eff8e09901dbb7dc9705f4de8a0dfe7882a9ed56982bd128e/Pillow-6.0.0-cp37-cp37m-win32.whl (1.7MB)
• |████████████████████████████████| 1.7MB 1.3MB/s
• Installing collected packages: Pillow
• Successfully installed Pillow-6.0.0
• Once this is done, you can import and then use the following two modules:
• Image,
• ImageFilter

The following is a coding sample:

The sharpened image is shown in Figure 8-4.

Note that the Image module has a class with the same name as the module, Image, although it is more convenient to construct an object of Image with the open statement rather than the constructor of Image class.

Once an image object has been generated with the open statement, we can check its format, size, and mode by looking at the format, size, and mode attributes and using the following methods of the Image class to manipulate the image object:

• • Image.convert(self, mode = None, matrix = None, dither = None, palette = 0, colors = 256) makes various conversions to the image object.

• • Image.copy(self) makes a copy and retains the original image object.
• • Image.crop(self, box=None) returns a rectangular region of the image, defined by box.
• • Image.draft(self, mode, size) returns a draft version of the image, such as a grey-scale version.
• • Image.effect_spread(self, distance) returns an image with pixels randomly spread throughout the image.
• • Image.filter(self, filter) filters this image using the given filter specified in the ImageFilter module.
• • Image.paste(self, im, box=None, mask=None) pastes another image (im) into this image.
• • Image.putalpha(self, alpha) adds or replaces the alpha layer in this image.
• • Image.putdata(self, data, scale = 1.0, offset = 0.0) copies a sequence of pixel data to this image.
• • Image.putpalette(self, data, rawmode = 'RGB') attaches a palette to this image.
• • Image.putpixel(self, xy, value) modifies the pixel at the given position.
• • Image.quantize(self, colors = 256, method = None, kmeans = 0, palette = None, dither = 1) converts the image to P mode with the specified number of colours.
• • Image.emap_palette(self, dest_map, source_palette = None) rewrites the image to reorder the palette.
• • Image.resize(self, size, resample = 0, box = None) returns a resized copy of this image.
• • Image.rotate(self, angle, resample = 0, expand = 0, center = None, translate = None, fillcolor = None) returns a rotated copy of this image.
• • Image.split(self), splits the image into individual bands, such as R, G, B.
• • Image.tobitmap(self, name='image') converts the image to an X11 bitmap.
• • Image.tobytes(self, encoder_name = 'raw', *args) returns the image as a bytes-object.
• • Image.toqimage(self) returns a QImage copy of this image.
• • Image.toqpixmap(self) returns a QPixmap copy of this image.
• • Image.transform(self, size, method, data=None, resample = 0, fill = 1, fillcolor = None) transforms this image to a given size but in the same mode as the original.
• • Image.transpose(self, method) transposes the image (flips or rotates in 90-degree steps).

There are other methods defined within the Image class for other purposes. You can find out more info about the Image class by running the following statement in Python interactive mode:

As we have seen from the above list, the Image class has provided a good set of methods to manipulate an image.

The ImageFilter module provides some filtering operations on images, as the name implies. These filtering operations include blurring, box blurring, contouring, colour transformation, detailing, edge enhancing, embossing, sharpening, smoothing, and more.