1
.. include:: common.txt
7
:synopsis: the top level pygame package
9
| :sl:`the top level pygame package`
11
The pygame package represents the top-level package for others to use. Pygame
12
itself is broken into many submodules, but this does not affect programs that
15
As a convenience, most of the top-level variables in pygame have been placed
16
inside a module named 'pygame.locals'. This is meant to be used with 'from
17
:mod:`pygame.locals` import \*', in addition to 'import pygame'.
19
When you 'import pygame' all available pygame submodules are automatically
20
imported. Be aware that some of the pygame modules are considered "optional",
21
and may not be available. In that case, Pygame will provide a placeholder
22
object instead of the module, which can be used to test for availability.
26
| :sl:`initialize all imported pygame modules`
27
| :sg:`init() -> (numpass, numfail)`
29
Initialize all imported Pygame modules. No exceptions will be raised if a
30
module fails, but the total number if successful and failed inits will be
31
returned as a tuple. You can always initialize individual modules manually,
32
but :func:`pygame.init` is a convenient way to get everything started. The
33
``init()`` functions for individual modules will raise exceptions when they
36
You may want to initalise the different modules seperately to speed up your
37
program or to not use things your game does not.
39
It is safe to call this ``init()`` more than once: repeated calls will have
40
no effect. This is true even if you have ``pygame.quit()`` all the modules.
46
| :sl:`uninitialize all pygame modules`
47
| :sg:`quit() -> None`
49
Uninitialize all pygame modules that have previously been initialized. When
50
the Python interpreter shuts down, this method is called regardless, so your
51
program should not need it, except when it wants to terminate its pygame
52
resources and continue. It is safe to call this function more than once:
53
repeated calls have no effect.
55
Note, that :func:`pygame.quit` will not exit your program. Consider letting
56
your program end in the same way a normal python program will end.
62
| :sl:`standard pygame exception`
63
| :sg:`raise pygame.error(message)`
65
This exception is raised whenever a pygame or ``SDL`` operation fails. You
66
can catch any anticipated problems and deal with the error. The exception is
67
always raised with a descriptive message about the problem.
69
Derived from the RuntimeError exception, which can also be used to catch
74
.. function:: get_error
76
| :sl:`get the current error message`
77
| :sg:`get_error() -> errorstr`
79
``SDL`` maintains an internal error message. This message will usually be
80
given to you when :func:`pygame.error` is raised. You will rarely need to
83
.. ## pygame.get_error ##
85
.. function:: set_error
87
| :sl:`set the current error message`
88
| :sg:`set_error(error_msg) -> None`
90
``SDL`` maintains an internal error message. This message will usually be
91
given to you when :func:`pygame.error` is raised. You will rarely need to
94
.. ## pygame.set_error ##
96
.. function:: get_sdl_version
98
| :sl:`get the version number of SDL`
99
| :sg:`get_sdl_version() -> major, minor, patch`
101
Returns the three version numbers of the ``SDL`` library. This version is
102
built at compile time. It can be used to detect which features may not be
103
available through Pygame.
105
get_sdl_version is new in pygame 1.7.0
107
.. ## pygame.get_sdl_version ##
109
.. function:: get_sdl_byteorder
111
| :sl:`get the byte order of SDL`
112
| :sg:`get_sdl_byteorder() -> int`
114
Returns the byte order of the ``SDL`` library. It returns ``LIL_ENDIAN`` for
115
little endian byte order and ``BIG_ENDIAN`` for big endian byte order.
117
get_sdl_byteorder is new in pygame 1.8
119
.. ## pygame.get_sdl_byteorder ##
121
.. function:: register_quit
123
| :sl:`register a function to be called when pygame quits`
124
| :sg:`register_quit(callable) -> None`
126
When :func:`pygame.quit` is called, all registered quit functions are
127
called. Pygame modules do this automatically when they are initializing.
128
This function is not be needed for regular pygame users.
130
.. ## pygame.register_quit ##
132
.. function:: encode_string
134
| :sl:`Encode a unicode or bytes object`
135
| :sg:`encode_string([obj [, encoding [, errors [, etype]]]]) -> bytes or None`
137
obj: If unicode, encode; if bytes, return unaltered; if anything else,
138
return None; if not given, raise SyntaxError.
140
encoding (string): If present, encoding to use. The default is
143
errors (string): If given, how to handle unencodable characters. The default
144
is 'backslashreplace'.
146
etype (exception type): If given, the exception type to raise for an
147
encoding error. The default is UnicodeEncodeError, as returned by
148
``PyUnicode_AsEncodedString()``. For the default encoding and errors values
149
there should be no encoding errors.
151
This function is used in encoding file paths. Keyword arguments are
154
Added in Pygame 1.9.2 (primarily for use in unit tests)
156
.. ## pygame.encode_string ##
158
.. function:: encode_file_path
160
| :sl:`Encode a unicode or bytes object as a file system path`
161
| :sg:`encode_file_path([obj [, etype]]) -> bytes or None`
163
obj: If unicode, encode; if bytes, return unaltered; if anything else,
164
return None; if not given, raise SyntaxError.
166
etype (exception type): If given, the exception type to raise for an
167
encoding error. The default is UnicodeEncodeError, as returned by
168
``PyUnicode_AsEncodedString()``.
170
This function is used to encode file paths in Pygame. Encoding is to the
171
codec as returned by ``sys.getfilesystemencoding()``. Keyword arguments are
174
Added in Pygame 1.9.2 (primarily for use in unit tests)
176
.. ## pygame.encode_file_path ##
178
:mod:`pygame.version`
179
=====================
181
.. module:: pygame.version
182
:synopsis: small module containing version information
184
| :sl:`small module containing version information`
186
This module is automatically imported into the pygame package and offers a few
187
variables to check with version of pygame has been imported.
191
| :sl:`version number as a string`
194
This is the version represented as a string. It can contain a micro release
195
number as well, ``e.g.``, '1.5.2'
197
.. ## pygame.version.ver ##
201
| :sl:`tupled integers of the version`
202
| :sg:`vernum = (1, 5, 3)`
204
This variable for the version can easily be compared with other version
205
numbers of the same format. An example of checking Pygame version numbers
206
would look like this:
210
if pygame.version.vernum < (1, 5):
211
print 'Warning, older version of Pygame (%s)' % pygame.version.ver
212
disable_advanced_features = True
214
.. ## pygame.version.vernum ##
216
.. ## pygame.version ##
added
removed
docs/_sources/ref/pygame.txt
