Copyright (c) Hyperion Entertainment and contributors.

Difference between revisions of "AmigaOS Manual: Python Modules and Packages"

From AmigaOS Documentation Wiki
Jump to navigation Jump to search
(Description added)
 
(187 intermediate revisions by the same user not shown)
Line 1: Line 1:
−
= Modules =
 +
= Amiga Specific Modules =
  +
  +
Amiga Python contains six Amiga specific modules:
  +
* '''amiga''' - provides access to the most common system calls
  +
* '''arexx''' - support for ARexx communication and ARexx hosts
  +
* '''asl''' - provides access to the requesters
  +
* '''catalog''' - provides access to the localization methods
  +
* '''icon''' - provides access to the icon methods
  +
* '''installer''' - provides access to the [[Installation_Utility|Installation Utility]] methods
  +
 
== amiga ==
  
== amiga ==
   
−
This module provides access to AmigaOS system functionality.
 +
This module provides access to the AmigaOS system functionality. The module's methods may only be used if the module has been imported. Below is an example how to import this module.
  +
  +
<syntaxhighlight lang="python">
  +
# Import amiga module
  +
import amiga
  +
</syntaxhighlight>
   
 
=== abort() ===
  
=== abort() ===
Line 8: Line 22:
 
abort ()
  
abort ()
   
−
Abort the interpreter immediately. Calling the function fails in the hardest way possible on the hosting operating system.
 +
Abort the interpreter immediately. Calling the abort method fails in the hardest way possible on the hosting operating system.
−
This function does not return!
 +
This method does not return!
   
 
=== access() ===
  
=== access() ===
   
−
access ( path, mode )
 +
have_access = access ( path, mode )
   
 
Use the real uid (User Identifier) or gid (Group Identifier) to test for access to a path. Note that most operations will use the effective uid/gid, therefore this routine can be used in a suid (Set Owner User ID) or sgid (Set Group ID) environment to test if the invoking user has the specified access to the path.
  
Use the real uid (User Identifier) or gid (Group Identifier) to test for access to a path. Note that most operations will use the effective uid/gid, therefore this routine can be used in a suid (Set Owner User ID) or sgid (Set Group ID) environment to test if the invoking user has the specified access to the path.
   
−
The mode argument can be F_OK to test existence, or the inclusive-OR of R_OK, W_OK, and X_OK.
 +
The mode argument can be '''F_OK''' to test existence, or the inclusive-OR of '''R_OK''', '''W_OK''', and '''X_OK'''.
  +
  +
Access() returns '''True''' if access is allowed, '''False''' if not.
   
 
=== chdir() ===
  
=== chdir() ===
Line 116: Line 132:
   
 
=== kill() ===
  
=== kill() ===
  +
  +
kill ( pid, sig )
  +
  +
Kill a process 'pid' with a signal 'sig'.
  +
 
=== link() ===
  
=== link() ===
  +
  +
link ( source, destination )
  +
  +
Create a hard link to a file.
  +
 
=== listdir() ===
  
=== listdir() ===
  +
  +
list_of_strings = listdir ( path )
  +
  +
Returns a list containing the names of the entries in the directory.
  +
  +
;path
  +
: Path of the directory to list.
  +
  +
The list is in arbitrary order. It does not include the special entries '.' and '..' even if they are present in the directory.
  +
 
=== lseek() ===
  
=== lseek() ===
  +
  +
newpos = lseek ( fd, pos, how )
  +
  +
Change file descriptor position.
  +
 
=== lstat() ===
  
=== lstat() ===
  +
  +
result = lstat ( path )
  +
  +
Like [[AmigaOS_Manual:_Python_Modules_and_Packages#stat.28.29|stat()]], but does not follow symbolic links.
  +
 
=== mkdir() ===
  
=== mkdir() ===
  +
  +
mkdir ( path, [, mode = 0777 ] )
  +
  +
Create a directory.
  +
 
=== open() ===
  
=== open() ===
  +
  +
fd = open ( filename, flag [, mode = 0777 ] )
  +
  +
Open a file for a low level input/output.
  +
 
=== pipe() ===
  
=== pipe() ===
  +
  +
read_end, write_end = pipe ()
  +
  +
Create a pipe.
  +
 
=== popen() ===
  
=== popen() ===
  +
  +
pipe = popen ( command [, mode = 'r' [, bufsize ] ] )
  +
  +
Open a pipe to or from a command returning a file object.
  +
 
=== putenv() ===
  
=== putenv() ===
  +
  +
putenv ( key, value )
  +
  +
Change or add an environment variable.
  +
 
=== read() ===
  
=== read() ===
  +
  +
string = read ( fd, buffersize )
  +
  +
This method will read a string from the previously opened file.
  +
 
=== remove() ===
  
=== remove() ===
  +
  +
remove ( path )
  +
  +
Remove a file.
  +
  +
;See also
  +
* [[AmigaOS_Manual:_Python_Modules_and_Packages#unlink.28.29|unlink()]]
  +
 
=== rename() ===
  
=== rename() ===
  +
  +
rename ( oldName, newName )
  +
  +
Rename a file or a directory.
  +
 
=== rmdir() ===
  
=== rmdir() ===
  +
  +
rmdir ( path )
  +
  +
Deletes the directory which path is passed as an argument. To be successful, the directory must be empty.
  +
 
=== stat() ===
  
=== stat() ===
  +
  +
statInfo = stat ( path )
  +
  +
Returns information on a file or a directory. When called, the method returns the following data structure:
  +
{| class="wikitable"
  +
! Name !! Description
  +
|-
  +
| '''st_mode''' || object's protection bits
  +
|-
  +
| '''st_ino''' || object's inode number
  +
|-
  +
| '''st_dev''' || object's device
  +
|-
  +
| '''st_nlink''' || number of hard links
  +
|-
  +
| '''st_uid''' || user ID of the owner
  +
|-
  +
| '''st_gid''' || group ID of the owner
  +
|-
  +
| '''st_size''' || size of the file object (bytes)
  +
|-
  +
| '''st_atime''' || time of most recent access
  +
|-
  +
| '''st_mtime''' || time of most recent content modification
  +
|-
  +
| '''st_ctime''' || time of most recent metadata change
  +
|}
  +
  +
;See also
  +
* [[AmigaOS_Manual:_Python_Modules_and_Packages#stat_float_times.28.29|stat_float_times()]]
  +
  +
; Example:
  +
Get information on file "myFile" and print its size:
  +
<syntaxhighlight lang="python">
  +
statInfo = amiga.stat ( "RAM:myFile" )
  +
  +
print ( statInfo.st_size )
  +
</syntaxhighlight>
  +
 
=== stat_float_times() ===
  
=== stat_float_times() ===
  +
  +
old_value = stat_float_times ( [ new_value ] )
  +
  +
Determines whether [[AmigaOS_Manual:_Python_Modules_and_Packages#stat.28.29|stat()]] represents time stamps as floating point numbers. If '''new_value''' is True, future calls to [[AmigaOS_Manual:_Python_Modules_and_Packages#stat.28.29|stat()]] will return floating point numbers, otherwise future calls will return integer numbers.
  +
  +
If '''new_value''' is omitted, the current setting will be returned.
  +
 
=== strerror() ===
  
=== strerror() ===
  +
  +
error_message = strerror ( code )
  +
  +
Translates an error code to a message string.
  +
  +
;Example
  +
Print the error message associated with the error code 17:
  +
<syntaxhighlight lang="python">
  +
amiga.strerror( 17 )
  +
</syntaxhighlight>
  +
 
=== system() ===
  
=== system() ===
  +
  +
exit_status = system ( command )
  +
  +
Execute the command (a string) in a subshell.
  +
  +
;Example
  +
Show how long the system has been running using the Shell command '''Uptime'''.
  +
<syntaxhighlight lang="python">
  +
amiga.system( "Uptime" )
  +
</syntaxhighlight>
  +
 
=== tempnam() ===
  
=== tempnam() ===
 
=== tmpfile() ===
  
=== tmpfile() ===
Line 145: Line 307:
 
== arexx ==
  
== arexx ==
   
  +
This module provides support for ARexx communication and ARexx hosts. The module's methods may only be used if the module has been imported. Below is an example how to import this module.
−
=== Msg() ===
  
  +
−
=== Port() ===
  
  +
<syntaxhighlight lang="python">
  +
# Import arexx module
  +
import arexx
  +
</syntaxhighlight>
  +
  +
=== Msg Class ===
  +
==== error() ====
  +
  +
Reply an ARexx message with an error.
  +
  +
==== getvar() ====
  +
  +
Get an ARexx variable through the context of the message.
  +
  +
==== reply() ====
  +
  +
Reply an ARexx message.
  +
  +
==== setvar() ====
  +
  +
Set an ARexx variable via the context of the message.
  +
  +
=== Port Class ===
  +
==== close() ====
  +
==== getmsg() ====
  +
==== wait() ====
  +
 
=== dorexx() ===
  
=== dorexx() ===
  +
  +
rc, rc2, result = dorexx ( port, message )
  +
  +
Send an ARexx message '''message''' to the supplied ARexx host port '''port'''.
  +
  +
; Example:
  +
Command Workbench to display its About requester:
  +
<syntaxhighlight lang="python">
  +
arexx.dorexx( 'WORKBENCH', 'menu window root invoke workbench.about' )
  +
</syntaxhighlight>
   
 
=== Variables ===
  
=== Variables ===
Line 156: Line 355:
 
== asl ==
  
== asl ==
   
−
This module contains AmigaOS-specific requester function for file and path queries, message boxes, ans similar aspects.
 +
This module contains AmigaOS-specific requester methods for file and path queries, message boxes, ans similar aspects. The methods may only be used if the module has been imported. Below is an example how to import this module.
  +
  +
<syntaxhighlight lang="python">
  +
# Import ASL module
  +
import asl
  +
</syntaxhighlight>
   
 
=== FileRequest() ===
  
=== FileRequest() ===
Line 176: Line 380:
 
Opens a message box with the given title and body text. The options on the dialog are taken from the 'buttons' argument. The 'buttons' string contains individual substrings separated by a '|'.
  
Opens a message box with the given title and body text. The options on the dialog are taken from the 'buttons' argument. The 'buttons' string contains individual substrings separated by a '|'.
   
−
The result of this function is the button number selected by the user. Numbering starts from left with 1, 2 and so on, but the final button is 0.
 +
The result of this method is the button number selected by the user. Numbering starts from left with 1, 2 and so on, but the final button is 0.
   
 
; Example:
  
; Example:
Line 190: Line 394:
 
* __name__
  
* __name__
   
−
= Packages =
 +
== catalog ==
  +
  +
This module allows you to read Amiga catalog files and retrieve localized string from them. The module's methods may only be used if the module has been imported. Below is an example how to import this module.
  +
  +
<syntaxhighlight lang="python">
  +
# Import catalog module
  +
import catalog
  +
</syntaxhighlight>
  +
  +
=== OpenCatalog() ===
  +
  +
catalog = OpenCatalog( catalogname, language, builtinlanguage )
  +
  +
Open a named catalog. Catalog contains all the text strings that an application uses.
  +
  +
; Example:
  +
Open a catalog of application '''myapplication''' using the system default language. For example, if the system language is Finnish, the OpenCatalog method will try to open '''myapplication''''s Finnish catalog. If the catalog does not exist, a builtin English catalog will be used.
  +
<syntaxhighlight lang="python">
  +
import catalog
  +
  +
try:
  +
myApplicationCatalog = catalog.OpenCatalog ( "myapplication.catalog", None, "english" )
  +
except:
  +
myApplicationCatalog = None
  +
</syntaxhighlight>
  +
  +
=== GetString() ===
  +
  +
string = GetString( stringid, defaultstring )
  +
  +
Get a string from a catalog. If the requested string ''stringid'' does not exist, the supplied ''defaultstring'' will be returned instead.
  +
  +
; Example:
  +
Get the 11th string from a catalog, which has previously been opened as a ''myApplicationCatalog'' object. If there is no such string, string "About..." will be returned.
  +
<syntaxhighlight lang="python">
  +
string = myApplicationCatalog.GetString ( 11, "About..." )
  +
</syntaxhighlight>
  +
  +
== icon ==
  +
  +
The icon module allows you to manipulate the information stored in the Amiga icon files. The module's methods may only be used if the module has been imported. Below is an example how to import this module.
  +
  +
<syntaxhighlight lang="python">
  +
# Import icon module
  +
import icon
  +
</syntaxhighlight>
  +
  +
=== DiskObject Class ===
  +
  +
disk_object = DiskObject( path )
  +
  +
Opens an icon file. The '''path''' argument is a path to the icon file to be opened without the icon file extension ".info". On success, the DiskObject method will return a "DiskObject" object which contains the following attributes:
  +
  +
{| class="wikitable"
  +
! Attribute !! Description
  +
|-
  +
| tooltypes || Icon tool types as a list of tuples
  +
|-
  +
| deftool || The default tool
  +
|-
  +
| stacksize || Program stack size
  +
|}
  +
  +
Attributes can be manipulated and saved back to the icon using the PutIcon() method.
  +
  +
;See also
  +
* PutIcon()
  +
  +
; Example:
  +
Open the "SYS:System/Shell" icon file ("SYS:System/Shell.info") and print its attributes.
  +
<syntaxhighlight lang="python">
  +
import icon # Include icon module
  +
  +
ic = icon.DiskObject( 'SYS:System/Shell' )
  +
print( 'Tool types: ' + str( ic.tooltypes ) )
  +
print( 'Default tool: ' + ic.deftool )
  +
print( 'Stack size: ' + str( ic.stacksize ) )
  +
</syntaxhighlight>
  +
  +
==== PutIcon() ====
  +
  +
dobj.PutIcon ( name [, notifywb ] )
  +
  +
Writes a previously created DiskObject object '''dobj''' (an icon) to disk. The '''name''' argument is a path to the icon file to be written without the icon file extension ".info". When '''notifywb''' is True, PutIcon() will ask Workbench to update the icon if it is displayed. By default '''notifywb''' is False.
  +
  +
;See also
  +
* DiskObject()
  +
  +
== installer ==
  +
  +
The installer module provides an interface to the [[Installation_Utility|Installation Utility]]. The provided methods allow you to create an installation script with a graphical user interface. The module's methods may only be used if the module objects has been imported. Below is an example how to import this module's objects.
  +
  +
<syntaxhighlight lang="python">
  +
# Import installer module
  +
from installer import *
  +
</syntaxhighlight>
  +
  +
{{Note|The installer module is available only within [[Installation_Utility|Installation Utility]].}}
  +
  +
=== AddButton() ===
  +
  +
AddButton( label, frame, weight, onclick )
  +
  +
Add a button to a GUI page.
  +
  +
;See also
  +
* AddCheckBox()
  +
* AddChooser()
  +
* AddLabel()
  +
* AddRadioButton()
  +
* AddSpace()
  +
* AddString()
  +
  +
;Example
  +
<syntaxhighlight lang="python">
  +
</syntaxhighlight>
  +
  +
=== AddCheckBox() ===
  +
  +
AddCheckBox( label, weight, checked, onclick )
  +
  +
Add a checkbox gadget to a GUI page.
  +
  +
;See also
  +
* AddButton()
  +
* AddChooser()
  +
* AddLabel()
  +
* AddRadioButton()
  +
* AddSpace()
  +
* AddString()
  +
  +
;Example
  +
<syntaxhighlight lang="python">
  +
</syntaxhighlight>
  +
  +
=== AddChooser() ===
  +
  +
AddChooser( label, choices, weight, selected, mode, onclick )
  +
  +
Add a chooser gadget to a GUI page.
  +
  +
;See also
  +
* AddButton()
  +
* AddCheckBox()
  +
* AddLabel()
  +
* AddRadioButton()
  +
* AddSpace()
  +
* AddString()
  +
  +
;Example
  +
<syntaxhighlight lang="python">
  +
</syntaxhighlight>
  +
  +
=== AddLabel() ===
  +
  +
AddLabel( label, frame, weight, align )
  +
  +
Add a text label to a GUI page.
  +
  +
;See also
  +
* AddButton()
  +
* AddCheckBox()
  +
* AddChooser()
  +
* AddRadioButton()
  +
* AddSpace()
  +
* AddString()
  +
  +
;Example
  +
<syntaxhighlight lang="python">
  +
</syntaxhighlight>
  +
  +
=== AddPackage() ===
  +
  +
AddPackage( type, name, description, optional, selected, diskspace, featuregroup, alternatepath, files )
  +
  +
Add a package to the installation.
  +
  +
;See also
  +
* IsPackageSelected()
  +
* SelectPackage()
  +
* SetPackageOption()
  +
  +
;Example
  +
<syntaxhighlight lang="python">
  +
</syntaxhighlight>
  +
  +
=== AddPostInstallAction() ===
  +
  +
;Example
  +
<syntaxhighlight lang="python">
  +
</syntaxhighlight>
  +
  +
=== AddRadioButton() ===
  +
  +
AddRadioButton( labellist, weight, selected, onclick )
  +
  +
Add a radiobutton gadget to a GUI page.
  +
  +
;See also
  +
* AddButton()
  +
* AddCheckBox()
  +
* AddChooser()
  +
* AddLabel()
  +
* AddSpace()
  +
* AddString()
  +
  +
;Example
  +
<syntaxhighlight lang="python">
  +
</syntaxhighlight>
  +
  +
=== AddSpace() ===
  +
  +
AddSpace( weight )
  +
  +
Add space to a GUI page's layout.
  +
  +
;See also
  +
* AddButton()
  +
* AddCheckBox()
  +
* AddChooser()
  +
* AddLabel()
  +
* AddRadioButton()
  +
* AddString()
  +
  +
;Example
  +
<syntaxhighlight lang="python">
  +
AddSpace( weight = 5 )
  +
</syntaxhighlight>
  +
  +
=== AddString() ===
  +
  +
AddString( label, value, weight, handler )
  +
  +
Add a string gadget to a GUI page.
  +
  +
;See also
  +
* AddButton()
  +
* AddCheckBox()
  +
* AddChooser()
  +
* AddLabel()
  +
* AddRadioButton()
  +
* AddSpace()
  +
* GetString()
  +
* SetString()
  +
  +
;Example
  +
<syntaxhighlight lang="python">
  +
</syntaxhighlight>
  +
  +
=== BeginGroup() ===
  +
  +
BeginGroup( orientation, label, frame, weight )
  +
  +
Begin a new layout group in a GUI page.
  +
  +
;See also
  +
* EndGroup()
  +
  +
;Example
  +
<syntaxhighlight lang="python">
  +
</syntaxhighlight>
  +
  +
=== EndGUI() ===
  +
  +
EndGUI()
  +
  +
End a GUI page's user interface definition.
  +
  +
;See also
  +
* StartGUI()
  +
  +
;Example
  +
<syntaxhighlight lang="python">
  +
EndGUI ()
  +
</syntaxhighlight>
  +
  +
=== EndGroup() ===
  +
  +
EndGroup()
  +
  +
End of layout group.
  +
  +
;See also
  +
* BeginGroup()
  +
  +
;Example
  +
<syntaxhighlight lang="python">
  +
EndGroup ()
  +
</syntaxhighlight>
  +
  +
=== GetDeviceList() ===
  +
  +
;Example
  +
<syntaxhighlight lang="python">
  +
</syntaxhighlight>
  +
  +
=== GetInteger() ===
  +
  +
;See also
  +
* SetInteger()
  +
  +
;Example
  +
<syntaxhighlight lang="python">
  +
</syntaxhighlight>
  +
  +
=== GetObject() ===
  +
  +
;See also
  +
* SetObject()
  +
  +
;Example
  +
<syntaxhighlight lang="python">
  +
</syntaxhighlight>
  +
  +
=== GetString() ===
  +
  +
text = GetString( page, stringid )
  +
  +
Get a string gadget content.
  +
  +
;See also
  +
* SetString()
  +
  +
;Example
  +
<syntaxhighlight lang="python">
  +
</syntaxhighlight>
  +
  +
=== GetUIAttr() ===
  +
  +
value = GetUIAttr( page, element, attribute )
  +
  +
Get a value of a GUI element's attribute.
  +
  +
;See also
  +
* SetUIAttr()
  +
  +
;Example
  +
<syntaxhighlight lang="python">
  +
</syntaxhighlight>
  +
  +
=== GotoPage() ===
  +
  +
GotoPage( page )
  +
  +
Go to the given page.
  +
  +
;Example
  +
<syntaxhighlight lang="python">
  +
</syntaxhighlight>
  +
  +
=== IsPackageSelected() ===
  +
  +
selected = IsPackageSelected( package )
  +
  +
Queries if a package is selected.
  +
  +
;See also
  +
* AddPackage()
  +
* SelectPackage()
  +
* SetPackageOption()
  +
  +
;Example
  +
<syntaxhighlight lang="python">
  +
from installer import *
  +
  +
myPackage = AddPackage ( type = FILEPACKAGE, name = "My Package", optional = False, selected = True, file = [ "MyApplication/" ] )
  +
  +
if IsPackageSelected ( myPackage ):
  +
print ( "Package selected." )
  +
</syntaxhighlight>
  +
  +
=== NewPage() ===
  +
  +
page = NewPage( type )
  +
  +
Creates a new installer page. The ''type'' argument tells what kind of page will be created. The available page types are:
  +
  +
;DESTINATION
  +
: A page to select a directory to serve as the target for the installation.
  +
: '''Note:''' this page is mandatory.
  +
  +
;FINISH
  +
: A message page that is specifically targeted at closing the installation. This page automatically gets the "finish" attribute set to make the installation change the "Cancel" to the "Finish" button.
  +
  +
;GUI
  +
: A page where GUI elements can be added and controlled via a Python handler.
  +
  +
;INSTALL
  +
: The presence of this page automatically triggers the installation of the selected packages.
  +
  +
;LICENSE
  +
: A brickwall page that displays a license agreement that only lets the user continue after accepting the license.
  +
: '''Note:''' the [[Installation_Utility|Installation Utility]] will look for a text file called "license_languagename.language.txt", if not found, it will look for a file called "license.txt".
  +
  +
;PROCESSING
  +
: A page to display a simple progress bar for doing some Python-scripted processing.
  +
  +
;README
  +
: A page that displays a text file from disk for reference/README purposes.
  +
: '''Note:''' the [[Installation_Utility|Installation Utility]] will look for a text file called "readme_languagename.language.txt", if not found, it will look for a file called "readme.txt".
  +
  +
;WELCOME
  +
: A message page, usually used for displaying a "welcome" message, although other uses are perfectly possible as well.
  +
: '''Note:''' this page is mandatory.
  +
  +
If successful, the method will return created page's number. Otherwise an OSError exception is raised.
  +
  +
;Example
  +
Add a welcome page:
  +
<syntaxhighlight lang="python">
  +
pageWelcome = NewPage ( WELCOME )
  +
SetString (
  +
pageWelcome, "message",
  +
"Welcome to the installation!"
  +
)
  +
</syntaxhighlight>
  +
  +
=== RunInstaller() ===
  +
  +
RunInstaller()
  +
  +
Runs the installation.
  +
  +
;Example
  +
Execute installation:
  +
<syntaxhighlight lang="python">
  +
RunInstaller ()
  +
</syntaxhighlight>
  +
  +
=== SelectPackage() ===
  +
  +
;See also
  +
* AddPackage()
  +
* IsPackageSelected()
  +
* SetPackageOption()
  +
  +
;Example
  +
<syntaxhighlight lang="python">
  +
</syntaxhighlight>
  +
  +
=== SetInteger() ===
  +
  +
SetInteger( page, integerid, value )
  +
  +
Set an interger variable on a page.
  +
  +
;See also
  +
* GetInteger()
  +
  +
;Example
  +
<syntaxhighlight lang="python">
  +
</syntaxhighlight>
  +
  +
=== SetObject() ===
  +
  +
SetObject( page, objectid, value )
  +
  +
Set a Python object variable on a page.
  +
  +
;See also
  +
* GetObject()
  +
  +
;Example
  +
<syntaxhighlight lang="python">
  +
</syntaxhighlight>
  +
  +
=== SetPackageOption() ===
  +
  +
SetPackageOption( package, option, value )
  +
  +
Set package option.
  +
  +
;See also
  +
* AddPackage()
  +
* IsPackageSelected()
  +
* SelectPackage()
  +
  +
;Example
  +
<syntaxhighlight lang="python">
  +
</syntaxhighlight>
  +
  +
=== SetString() ===
  +
  +
SetString( page, stringid, text )
  +
  +
Set a page's string gadget value.
  +
  +
;See also
  +
* GetString()
  +
  +
;Example
  +
<syntaxhighlight lang="python">
  +
</syntaxhighlight>
  +
  +
=== SetUIAttr() ===
  +
  +
SetUIAttr( page, element, attribute, value )
  +
  +
Set a value of a GUI element attribute.
  +
  +
;See also
  +
* GetUIAttr()
  +
  +
;Example
  +
<syntaxhighlight lang="python">
  +
</syntaxhighlight>
  +
  +
=== StartGUI() ===
  +
  +
StartGUI( page )
  +
  +
Start a GUI page's user interface definition.
  +
  +
;See also
  +
* EndGUI()
  +
  +
;Example
  +
<syntaxhighlight lang="python">
  +
</syntaxhighlight>
  +
  +
=== Variables ===
  +
* ALIGN_BLOCK
  +
* ALIGN_CENTER
  +
* ALIGN_LEFT
  +
* ALIGN_RIGHT
  +
* ARCHIVEPACKAGE
  +
* BOX_FRAME
  +
* BUTTON_FRAME
  +
* CANCEL
  +
* CHOOSER_DROPDOWN
  +
* CHOOSER_POPUP
  +
* DESTINATION
  +
* DROPBOX_FRAME
  +
* FIELD_FRAME
  +
* FILEPACKAGE
  +
* FINISH
  +
* GROUP_FRAME
  +
* GROUP_HORIZONTAL
  +
* GROUP_VERTICAL
  +
* GUI
  +
* GUI_ACTIVE
  +
* GUI_CHECKED
  +
* GUI_LABEL
  +
* GUI_ONCLICK
  +
* GUI_SELECTED
  +
* GUI_STRING
  +
* HANDLERPACKAGE
  +
* ID_BUSY_DISK
  +
* ID_CON
  +
* ID_DISKSTATE_VALIDATED
  +
* ID_DISKSTATE_VALIDATING
  +
* ID_DISKSTATE_WRITE_PROTECTED
  +
* ID_DOS_DISK
  +
* ID_FASTDIR_DOS_DISK
  +
* ID_FASTDIR_FFS_DISK
  +
* ID_FSS_DISK
  +
* ID_INTER_DOS_DISK
  +
* ID_INTER_FFS_DISK
  +
* ID_KICKSTART_DISK
  +
* ID_LONGNAME_DOS_DISK
  +
* ID_LONGNAME_FFS_DISK
  +
* ID_MSDOS_DISK
  +
* ID_NOT_REALLY_DOS
  +
* ID_NO_DISK_PRESENT
  +
* ID_RAWCON
  +
* ID_UNREADABLE_DISK
  +
* ID_VALIDATED
  +
* ID_VALIDATING
  +
* ID_WRITE_PROTECTED
  +
* INHIBIT_BACKWARD
  +
* INHIBIT_CANCEL
  +
* INHIBIT_FORWARD
  +
* INSTALL
  +
* JUMP
  +
* LICENSE
  +
* NEXT
  +
* NONE_FRAME
  +
* PACKAGESELECT
  +
* PREVIOUS
  +
* PROCESSING
  +
* README
  +
* SBAR_HORIZ_FRAME
  +
* SBAR_VERT_FRAME
  +
* STANDARD_FRAME
  +
* THIN_FRAME
  +
* WELCOME
  +
  +
= Amiga Specific Packages =
  +
  +
The current Amiga Python release does not contain any Amiga specific packages.

Latest revision as of 21:33, 31 July 2022

Contents

Amiga Specific Modules

Amiga Python contains six Amiga specific modules:

  • amiga - provides access to the most common system calls
  • arexx - support for ARexx communication and ARexx hosts
  • asl - provides access to the requesters
  • catalog - provides access to the localization methods
  • icon - provides access to the icon methods
  • installer - provides access to the Installation Utility methods

amiga

This module provides access to the AmigaOS system functionality. The module's methods may only be used if the module has been imported. Below is an example how to import this module. 

# Import amiga module
import amiga

abort()

 abort ()

Abort the interpreter immediately. Calling the abort method fails in the hardest way possible on the hosting operating system. This method does not return!

access()

 have_access = access ( path, mode )

Use the real uid (User Identifier) or gid (Group Identifier) to test for access to a path. Note that most operations will use the effective uid/gid, therefore this routine can be used in a suid (Set Owner User ID) or sgid (Set Group ID) environment to test if the invoking user has the specified access to the path.

The mode argument can be F_OK to test existence, or the inclusive-OR of R_OK, W_OK, and X_OK.

Access() returns True if access is allowed, False if not.

chdir()

 chdir ( path )

Change the current working directory to the specified path.

chmod()

 chmod ( path, mode )

Change the access permissions of a file.

chown()

  chown ( path, uid, gid )

Change the owner and group id of path to the numeric uid and gid.

close()

  close ( fd )

Close a file descriptor (for low level I/O).

dup()

  fd2 = dup ( fd )

Return a duplicate of a file descriptor.

dup2()

  dup2 ( old_fd, new_fd )

Duplicate file descriptor.

fdopen()

  file_object = fdopen ( fd [, mode = 'r' [, bufsize ] ] )

Return an open file object connected to a file descriptor.

fstat()

  result = fstat ( fd )

Like stat(), but for an open file descriptor.

ftruncate()

  ftruncate ( fd, length )

Truncate a file to a specified length.

getcpu()

  getcpu ()

Get the CPU model string.

getcwd()

  path = getcwd ()

Return a string representing the current working directory.

getcwdu()

  path = getcwdu ()

Return a unicode string representing the current working directory.

getmachine()

  getmachine ()

Get the machine model string.

getpid()

  pid = getpid ()

Return the current process ID.

getports()

  list_of_strings = getports ()

Returns a list of public message port names.

isatty()

  bool = isatty ( fd )

Return True if the file descriptor 'fd' is an open file descriptor connected to the slave end of a terminal.

kill()

  kill ( pid, sig )

Kill a process 'pid' with a signal 'sig'.

link()

  link ( source, destination )

Create a hard link to a file.

listdir()

  list_of_strings = listdir ( path )

Returns a list containing the names of the entries in the directory.

path
Path of the directory to list.

The list is in arbitrary order. It does not include the special entries '.' and '..' even if they are present in the directory.

lseek()

  newpos = lseek ( fd, pos, how )

Change file descriptor position.

lstat()

  result = lstat ( path )

Like stat(), but does not follow symbolic links.

mkdir()

  mkdir ( path, [, mode = 0777 ] )

Create a directory.

open()

  fd = open ( filename, flag [, mode = 0777 ] )

Open a file for a low level input/output.

pipe()

  read_end, write_end = pipe ()

Create a pipe.

popen()

  pipe = popen ( command [, mode = 'r' [, bufsize ] ] )

Open a pipe to or from a command returning a file object.

putenv()

  putenv ( key, value )

Change or add an environment variable.

read()

  string = read ( fd, buffersize )

This method will read a string from the previously opened file.

remove()

  remove ( path )

Remove a file.

See also

rename()

  rename ( oldName, newName )

Rename a file or a directory.

rmdir()

  rmdir ( path )

Deletes the directory which path is passed as an argument. To be successful, the directory must be empty.

stat()

  statInfo = stat ( path )

Returns information on a file or a directory. When called, the method returns the following data structure:

Name Description
st_mode object's protection bits
st_ino object's inode number
st_dev object's device
st_nlink number of hard links
st_uid user ID of the owner
st_gid group ID of the owner
st_size size of the file object (bytes)
st_atime time of most recent access
st_mtime time of most recent content modification
st_ctime time of most recent metadata change
See also
Example

Get information on file "myFile" and print its size: 

statInfo = amiga.stat ( "RAM:myFile" )
 
print ( statInfo.st_size )

stat_float_times()

 old_value = stat_float_times ( [ new_value ] )

Determines whether stat() represents time stamps as floating point numbers. If new_value is True, future calls to stat() will return floating point numbers, otherwise future calls will return integer numbers.

If new_value is omitted, the current setting will be returned.

strerror()

 error_message = strerror ( code )

Translates an error code to a message string.

Example

Print the error message associated with the error code 17: 

amiga.strerror( 17 )

system()

 exit_status = system ( command )

Execute the command (a string) in a subshell.

Example

Show how long the system has been running using the Shell command Uptime. 

amiga.system( "Uptime" )

tempnam()

tmpfile()

tmpnam()

umask()

unlink()

urandom()

utime()

waitforport()

write()

arexx

This module provides support for ARexx communication and ARexx hosts. The module's methods may only be used if the module has been imported. Below is an example how to import this module. 

# Import arexx module
import arexx

Msg Class

error()

Reply an ARexx message with an error.

getvar()

Get an ARexx variable through the context of the message.

reply()

Reply an ARexx message.

setvar()

Set an ARexx variable via the context of the message.

Port Class

close()

getmsg()

wait()

dorexx()

 rc, rc2, result = dorexx ( port, message )

Send an ARexx message message to the supplied ARexx host port port.

Example

Command Workbench to display its About requester: 

arexx.dorexx( 'WORKBENCH', 'menu window root invoke workbench.about' )

Variables

  • __doc__
  • __file__
  • __name__

asl

This module contains AmigaOS-specific requester methods for file and path queries, message boxes, ans similar aspects. The methods may only be used if the module has been imported. Below is an example how to import this module. 

# Import ASL module
import asl

FileRequest()

 drawer, file = FileRequest ( title, drawer, filename, pattern )

Opens a file select requester with the given title, the drawer and filename gadgets predefined by drawer and title. If a pattern is given, a pattern gadget is also displayed and pre-set with the given pattern. The result is a tuple drawer, filename which relects the choice of the user.

Example

Opens up a file requester in T: with 'my.log' as a default name, and a filter set to '#?.log': 

drawer, file = asl.FileRequest('Python File Request', 'T:', 'my.log', '#?.log' )

MessageBox()

 result = MessageBox( title, body_text, buttons )

Opens a message box with the given title and body text. The options on the dialog are taken from the 'buttons' argument. The 'buttons' string contains individual substrings separated by a '|'.

The result of this method is the button number selected by the user. Numbering starts from left with 1, 2 and so on, but the final button is 0.

Example

Puts up a requester asking for a 'Yes' or 'No' answer: 

result = asl.MessageBox('Python Request', 'AmigaOS rules', 'Yes|No')

Selecting 'Yes' returns 1 and selecting 'No' returns 0.

Variables

  • __doc__
  • __file__
  • __name__

catalog

This module allows you to read Amiga catalog files and retrieve localized string from them. The module's methods may only be used if the module has been imported. Below is an example how to import this module. 

# Import catalog module
import catalog

OpenCatalog()

 catalog = OpenCatalog( catalogname, language, builtinlanguage )

Open a named catalog. Catalog contains all the text strings that an application uses.

Example

Open a catalog of application myapplication using the system default language. For example, if the system language is Finnish, the OpenCatalog method will try to open myapplication's Finnish catalog. If the catalog does not exist, a builtin English catalog will be used. 

import catalog
 
try:
    myApplicationCatalog = catalog.OpenCatalog ( "myapplication.catalog", None, "english" )
except:
    myApplicationCatalog = None

GetString()

 string = GetString( stringid, defaultstring )

Get a string from a catalog. If the requested string stringid does not exist, the supplied defaultstring will be returned instead.

Example

Get the 11th string from a catalog, which has previously been opened as a myApplicationCatalog object. If there is no such string, string "About..." will be returned. 

string = myApplicationCatalog.GetString ( 11, "About..." )

icon

The icon module allows you to manipulate the information stored in the Amiga icon files. The module's methods may only be used if the module has been imported. Below is an example how to import this module. 

# Import icon module
import icon

DiskObject Class

 disk_object = DiskObject( path )

Opens an icon file. The path argument is a path to the icon file to be opened without the icon file extension ".info". On success, the DiskObject method will return a "DiskObject" object which contains the following attributes:

Attribute Description
tooltypes Icon tool types as a list of tuples
deftool The default tool
stacksize Program stack size

Attributes can be manipulated and saved back to the icon using the PutIcon() method.

See also
  • PutIcon()
Example

Open the "SYS:System/Shell" icon file ("SYS:System/Shell.info") and print its attributes. 

import icon # Include icon module
 
ic = icon.DiskObject( 'SYS:System/Shell' )
print( 'Tool types: ' + str( ic.tooltypes ) )
print( 'Default tool: ' + ic.deftool )
print( 'Stack size: ' + str( ic.stacksize ) )

PutIcon()

 dobj.PutIcon ( name [, notifywb ] )

Writes a previously created DiskObject object dobj (an icon) to disk. The name argument is a path to the icon file to be written without the icon file extension ".info". When notifywb is True, PutIcon() will ask Workbench to update the icon if it is displayed. By default notifywb is False.

See also
  • DiskObject()

installer

The installer module provides an interface to the Installation Utility. The provided methods allow you to create an installation script with a graphical user interface. The module's methods may only be used if the module objects has been imported. Below is an example how to import this module's objects. 

# Import installer module
from installer import *
Note
The installer module is available only within Installation Utility.

AddButton()

 AddButton( label, frame, weight, onclick )

Add a button to a GUI page.

See also
  • AddCheckBox()
  • AddChooser()
  • AddLabel()
  • AddRadioButton()
  • AddSpace()
  • AddString()
Example
 

AddCheckBox()

 AddCheckBox( label, weight, checked, onclick )

Add a checkbox gadget to a GUI page.

See also
  • AddButton()
  • AddChooser()
  • AddLabel()
  • AddRadioButton()
  • AddSpace()
  • AddString()
Example
 

AddChooser()

 AddChooser( label, choices, weight, selected, mode, onclick )

Add a chooser gadget to a GUI page.

See also
  • AddButton()
  • AddCheckBox()
  • AddLabel()
  • AddRadioButton()
  • AddSpace()
  • AddString()
Example
 

AddLabel()

 AddLabel( label, frame, weight, align )

Add a text label to a GUI page.

See also
  • AddButton()
  • AddCheckBox()
  • AddChooser()
  • AddRadioButton()
  • AddSpace()
  • AddString()
Example
 

AddPackage()

 AddPackage( type, name, description, optional, selected, diskspace, featuregroup, alternatepath, files )

Add a package to the installation.

See also
  • IsPackageSelected()
  • SelectPackage()
  • SetPackageOption()
Example
 

AddPostInstallAction()

Example
 

AddRadioButton()

 AddRadioButton( labellist, weight, selected, onclick )

Add a radiobutton gadget to a GUI page.

See also
  • AddButton()
  • AddCheckBox()
  • AddChooser()
  • AddLabel()
  • AddSpace()
  • AddString()
Example
 

AddSpace()

 AddSpace( weight )

Add space to a GUI page's layout.

See also
  • AddButton()
  • AddCheckBox()
  • AddChooser()
  • AddLabel()
  • AddRadioButton()
  • AddString()
Example
AddSpace( weight = 5 )

AddString()

 AddString( label, value, weight, handler )

Add a string gadget to a GUI page.

See also
  • AddButton()
  • AddCheckBox()
  • AddChooser()
  • AddLabel()
  • AddRadioButton()
  • AddSpace()
  • GetString()
  • SetString()
Example
 

BeginGroup()

 BeginGroup( orientation, label, frame, weight )

Begin a new layout group in a GUI page.

See also
  • EndGroup()
Example
 

EndGUI()

 EndGUI()

End a GUI page's user interface definition.

See also
  • StartGUI()
Example
EndGUI ()

EndGroup()

 EndGroup()

End of layout group.

See also
  • BeginGroup()
Example
EndGroup ()

GetDeviceList()

Example
 

GetInteger()

See also
  • SetInteger()
Example
 

GetObject()

See also
  • SetObject()
Example
 

GetString()

 text = GetString( page, stringid )

Get a string gadget content.

See also
  • SetString()
Example
 

GetUIAttr()

 value = GetUIAttr( page, element, attribute )

Get a value of a GUI element's attribute.

See also
  • SetUIAttr()
Example
 

GotoPage()

 GotoPage( page )

Go to the given page.

Example
 

IsPackageSelected()

 selected = IsPackageSelected( package )

Queries if a package is selected.

See also
  • AddPackage()
  • SelectPackage()
  • SetPackageOption()
Example
from installer import *
 
myPackage = AddPackage ( type = FILEPACKAGE, name = "My Package", optional = False, selected = True, file = [ "MyApplication/" ] )
 
if IsPackageSelected ( myPackage ):
    print ( "Package selected." )

NewPage()

 page = NewPage( type )

Creates a new installer page. The type argument tells what kind of page will be created. The available page types are:

DESTINATION
A page to select a directory to serve as the target for the installation.
Note: this page is mandatory.
FINISH
A message page that is specifically targeted at closing the installation. This page automatically gets the "finish" attribute set to make the installation change the "Cancel" to the "Finish" button.
GUI
A page where GUI elements can be added and controlled via a Python handler.
INSTALL
The presence of this page automatically triggers the installation of the selected packages.
LICENSE
A brickwall page that displays a license agreement that only lets the user continue after accepting the license.
Note: the Installation Utility will look for a text file called "license_languagename.language.txt", if not found, it will look for a file called "license.txt".
PROCESSING
A page to display a simple progress bar for doing some Python-scripted processing.
README
A page that displays a text file from disk for reference/README purposes.
Note: the Installation Utility will look for a text file called "readme_languagename.language.txt", if not found, it will look for a file called "readme.txt".
WELCOME
A message page, usually used for displaying a "welcome" message, although other uses are perfectly possible as well.
Note: this page is mandatory.

If successful, the method will return created page's number. Otherwise an OSError exception is raised.

Example

Add a welcome page: 

pageWelcome = NewPage ( WELCOME )
SetString (
    pageWelcome, "message", 
    "Welcome to the installation!"
)

RunInstaller()

 RunInstaller()

Runs the installation.

Example

Execute installation: 

RunInstaller ()

SelectPackage()

See also
  • AddPackage()
  • IsPackageSelected()
  • SetPackageOption()
Example
 

SetInteger()

 SetInteger( page, integerid, value )

Set an interger variable on a page.

See also
  • GetInteger()
Example
 

SetObject()

 SetObject( page, objectid, value )

Set a Python object variable on a page.

See also
  • GetObject()
Example
 

SetPackageOption()

 SetPackageOption( package, option, value )

Set package option.

See also
  • AddPackage()
  • IsPackageSelected()
  • SelectPackage()
Example
 

SetString()

 SetString( page, stringid, text )

Set a page's string gadget value.

See also
  • GetString()
Example
 

SetUIAttr()

  SetUIAttr( page, element, attribute, value )

Set a value of a GUI element attribute.

See also
  • GetUIAttr()
Example
 

StartGUI()

 StartGUI( page )

Start a GUI page's user interface definition.

See also
  • EndGUI()
Example
 

Variables

  • ALIGN_BLOCK
  • ALIGN_CENTER
  • ALIGN_LEFT
  • ALIGN_RIGHT
  • ARCHIVEPACKAGE
  • BOX_FRAME
  • BUTTON_FRAME
  • CANCEL
  • CHOOSER_DROPDOWN
  • CHOOSER_POPUP
  • DESTINATION
  • DROPBOX_FRAME
  • FIELD_FRAME
  • FILEPACKAGE
  • FINISH
  • GROUP_FRAME
  • GROUP_HORIZONTAL
  • GROUP_VERTICAL
  • GUI
  • GUI_ACTIVE
  • GUI_CHECKED
  • GUI_LABEL
  • GUI_ONCLICK
  • GUI_SELECTED
  • GUI_STRING
  • HANDLERPACKAGE
  • ID_BUSY_DISK
  • ID_CON
  • ID_DISKSTATE_VALIDATED
  • ID_DISKSTATE_VALIDATING
  • ID_DISKSTATE_WRITE_PROTECTED
  • ID_DOS_DISK
  • ID_FASTDIR_DOS_DISK
  • ID_FASTDIR_FFS_DISK
  • ID_FSS_DISK
  • ID_INTER_DOS_DISK
  • ID_INTER_FFS_DISK
  • ID_KICKSTART_DISK
  • ID_LONGNAME_DOS_DISK
  • ID_LONGNAME_FFS_DISK
  • ID_MSDOS_DISK
  • ID_NOT_REALLY_DOS
  • ID_NO_DISK_PRESENT
  • ID_RAWCON
  • ID_UNREADABLE_DISK
  • ID_VALIDATED
  • ID_VALIDATING
  • ID_WRITE_PROTECTED
  • INHIBIT_BACKWARD
  • INHIBIT_CANCEL
  • INHIBIT_FORWARD
  • INSTALL
  • JUMP
  • LICENSE
  • NEXT
  • NONE_FRAME
  • PACKAGESELECT
  • PREVIOUS
  • PROCESSING
  • README
  • SBAR_HORIZ_FRAME
  • SBAR_VERT_FRAME
  • STANDARD_FRAME
  • THIN_FRAME
  • WELCOME

Amiga Specific Packages

The current Amiga Python release does not contain any Amiga specific packages.

Retrieved from "http://wiki.amigaos.net/w/index.php?title=AmigaOS_Manual:_Python_Modules_and_Packages&oldid=12319"