1.. TUTORIAL:Import and Initialize
2
3.. include:: common.txt
4
5********************************************
6  Pygame Tutorials - Import and Initialize
7********************************************
8
9Import and Initialize
10=====================
11
12.. rst-class:: docinfo
13
14:Author: Pete Shinners
15:Contact: pete@shinners.org
16
17
18Getting pygame imported and initialized is a very simple process. It is also
19flexible enough to give you control over what is happening. Pygame is a
20collection of different modules in a single python package. Some of the
21modules are written in C, and some are written in python. Some modules
22are also optional, and might not always be present.
23
24This is just a quick introduction on what is going on when you import pygame.
25For a clearer explanation definitely see the pygame examples.
26
27
28Import
29------
30
31First we must import the pygame package. Since pygame version 1.4 this
32has been updated to be much easier. Most games will import all of pygame like this. ::
33
34  import pygame
35  from pygame.locals import *
36
37The first line here is the only necessary one. It imports all the available pygame
38modules into the pygame package. The second line is optional, and puts a limited
39set of constants and functions into the global namespace of your script.
40
41An important thing to keep in mind is that several pygame modules are optional.
42For example, one of these is the font module. When  you "import pygame", pygame
43will check to see if the font module is available. If the font module is available
44it will be imported as "pygame.font". If the module is not available, "pygame.font"
45will be set to None. This makes it fairly easy to later on test if the font module is available.
46
47
48Init
49----
50
51Before you can do much with pygame, you will need to initialize it. The most common
52way to do this is just make one call. ::
53
54  pygame.init()
55
56This will attempt to initialize all the pygame modules for you. Not all pygame modules
57need to be initialized, but this will automatically initialize the ones that do. You can
58also easily initialize each pygame module by hand. For example to only initialize the
59font module you would just call. ::
60
61  pygame.font.init()
62
63Note that if there is an error when you initialize with "pygame.init()", it will silently fail.
64When hand initializing modules like this, any errors will raise an exception. Any
65modules that must be initialized also have a "get_init()" function, which will return true
66if the module has been initialized.
67
68It is safe to call the init() function for any module more than once.
69
70
71Quit
72----
73
74Modules that are initialized also usually have a quit() function that will clean up.
75There is no need to explicitly call these, as pygame will cleanly quit all the
76initialized modules when python finishes.
77