home *** CD-ROM | disk | FTP | other *** search
/ AmigActive 15 / AACD15.ISO / AACD / Programming / Python2 / Docs / Amiga / Dos_module < prev    next >
Encoding:
Text File  |  2000-10-03  |  11.3 KB  |  333 lines
  1.  
  2. ***************************************************************************
  3.  
  4.                         PYTHON dos.library SUPPORT
  5.  
  6.                           Dos and Doslib modules
  7.     
  8.                    by Irmen de Jong - irmen@bigfoot.com
  9.  
  10.                           Last update: 1-Oct-2000
  11.                           (raw console functions)
  12.  
  13.  
  14. ***************************************************************************
  15.  
  16.  
  17.  
  18. ***************************************************************************
  19.  
  20.                               MODULE: Doslib
  21.  
  22.                             FILE: N/A (builtin)
  23.  
  24. ***************************************************************************
  25.  
  26. This module provides the low-level dos.library functionality.
  27.  
  28. IMPORTANT:   It  is  DISCOURAGED  to  use this module directly, use the Dos
  29. module  instead  (see  below).  The Dos module imports everything from this
  30. module  so  you can access everything through the Dos module instead.  This
  31. is  much  like  how the string module uses the builtin strop module:  don't
  32. use the builtin lowlevel module directly!
  33.  
  34. This module defines the following exception:
  35.  
  36.   error        - The exception that will be raised when an
  37.           error occurs related to dos.library. ('Doslib.error')
  38.  
  39.  
  40. +--------------------------------------+
  41. |                                      |
  42. |          DEFINED FUNCTIONS           |
  43. |                                      |
  44. +--------------------------------------+
  45.  
  46. ReadArgs
  47.     INTENTIONALLY UNDOCUMENTED. USE ArgParser CLASS FROM `Dos' MODULE!
  48.  
  49. WaitSignal(what)
  50.     Generic Wait() function to wait for signals, modeled after the `select'
  51.     function. Usage: (sigs,objlist) = WaitSignal(what)
  52.        what = integer, object, or a list of ints and/or objects.
  53.        Integers are sigmask values. Objects must have a 'signal' attribute
  54.        which is their sigmask value. When a list is given the sigmasks of
  55.        the items are or-ed together (max 32 items).
  56.     RESULT: sigs = the signals that occured (sigmask).
  57.             objlist = a list of the objects whose signal occured.
  58.     NOTE: any signals that were detected are cleared when WaitSignal()
  59.     returns. Signals that were not waited upon are not cleared.
  60.  
  61. CheckSignal(what)
  62.     Like WaitSignal (see above) but DOESN'T WAIT, merely checks if certain
  63.     signals are set. NOTE: any signals that were detected are cleared when
  64.     CheckSignal() returns. Signals that were not checked upon are not
  65.     cleared.
  66.  
  67. CompareDates(d1,d2)
  68.     Compares the two 3-tuple DateStamps d1 and d2 and returns:
  69.     <0 if d1 is later than d2
  70.      0 if d1 = d2
  71.     >0 if d1 is before d2
  72.  
  73. DateStamp()
  74.     Returns 3-tuple AmigaDOS DateStamp (current date & time).
  75.  
  76. DateToStr(date,format=FORMAT_DOS,flags=0)
  77.     Convert 3-tuple DateStamp to readable 3-tuple date string.
  78.     date = DateStamp
  79.     format and flags are optional.
  80.     format = how to format the string (see Dos.py module for definitions)
  81.     flags = flags (see Dos.py module for definitions)
  82.     
  83. StrToDate(dstr [,timestring, format = FORMAT_DOS, flags = 0] )
  84.     Convert AmigaDOS date string to AmigaDOS DateStamp.
  85.     dstr = date string (like '27-Aug-96')
  86.     timestring = time string (optional, like '16:12:00')
  87.     format = string format (optional, see Dos.py module for definitions)
  88.     flags = flags (see Dos.py module for definitions)
  89.     
  90. Fault(err [,header])
  91.     Returns DOS error message string.
  92.     err = Dos error code
  93.     header = error header string (optional, defaults to None which means
  94.              no header)
  95.  
  96. GetProgramDir()
  97.     Returns the directory the program (the python interpreter) was launched
  98.     from. Will usually be the directory where your Python: assign points to.
  99.     Returns empy string when Python is launched as resident program (note
  100.     that at the time of writing this is not possible).
  101.  
  102. GetProgramName()
  103.     Returns the full CLI name of the program (the python interpreter).
  104.     Will fail if Python is launched from the Workbench.
  105.     
  106. Inhibit(drive, switch=1)
  107.     Inhibits the specified drive (like 'HD0:') from access ("XXX: BUSY"
  108.     appears on the Workbench). Use '1' as switch to inhibit, '0' to remove
  109.     the restrictions (defaults to 1 when omitted).
  110.  
  111. IoErr()
  112.     Returns last DOS IoErr() error value.
  113.  
  114. SetIoErr(err)
  115.     Set new DOS IoErr() error value, and returns previous value.
  116.  
  117. IsFileSystem(path)
  118.     Checks if path is a filesystem device.
  119.  
  120. Relabel(oldvolname,newvolname)
  121.     Relabel a disk.
  122.     oldvolname = old volume name (including :)
  123.     newvolname = new volume name (without :)
  124.     
  125. SetProtection(file,protbits)
  126.     Set DOS file protection bits.
  127.     file = filename
  128.     protbits = protection bits for this file (see Dos.py module for
  129.                definitions)
  130.  
  131. SetComment(file,comment)
  132.     Set DOS file comment string.
  133.     file = filename
  134.     comment = file comment string for this file
  135.  
  136. SetFileDate(file, datestamp)
  137.     Sets the file's datestamp to the given datestamp.
  138.  
  139. SetOwner(file, uid, gid)
  140.     Sets the file's owner UID and owner GID.
  141.     Note that this call needs Kickstart 3.0 or higher.
  142.     
  143. Examine(file)
  144.     Examine a file or directory. Returns the following 10-tuple:
  145.     (filename,size,type,protection,diskkey,#blocks,
  146.      3-tuple DateStamp, comment, owner UID, owner GID )
  147.     The indexes of these members are defined in the Dos module;
  148.     fib_FileName, fib_Size,....  See Dos.py.
  149.  
  150. Info(drivename)
  151.     Returns information on the specified drive, as the following 7-tuple:
  152.     (NumSoftErrors, UnitNumber, DiskState, NumBlocks, NumBlocksUsed,
  153.      BytesPerBlock, DiskType, InUse).   (all 7 are integers).
  154.     The indexes of these members are defined in the Dos module;
  155.     id_NumSoftErrors, id_UnitNumber,....  See Dos.py.
  156.  
  157. DS2time(ds)
  158.     Convert DateStamp tuple to time() value (see time module)
  159.  
  160. time2DS
  161.     Convert time() value (see time module) to DateStamp tuple
  162.  
  163. SetMode(mode)        *** NEW ***
  164.     Sets the console mode, mode can be MODE_RAW (raw input mode) or MODE_CON
  165.     (normal line-buffered console mode).
  166.  
  167. WaitForChar(timeout)    *** NEW ***
  168.     When console is in RAW mode, waits for a character to be available
  169.     for reading. 'timeout' is a timeout in microseconds.
  170.  
  171. GetChar()        *** NEW ***
  172.     When console is in RAW mode, returns the next character available for
  173.     reading.
  174.     
  175. PutChar(char)        *** NEW ***
  176.     Writes a character to the output (unbuffered).
  177.  
  178. PutString(string)    *** NEW ***
  179.     Writes a string to the output (unbuffered).
  180.  
  181.  
  182.  
  183. ***************************************************************************
  184.  
  185.                                 MODULE: Dos
  186.  
  187.                                FILE: Dos.py
  188.  
  189. ***************************************************************************
  190.  
  191. This module is the interface to the Amiga's dos.library.
  192.  
  193. IMPORTANT:  this module uses the builtin Doslib module.  Don't use it
  194. yourself directly, always use the `Dos' module.
  195.  
  196. NOTE:
  197.  The whole lot of Dos LVO's that are not covered are considered:
  198.     - not useful;
  199.  or - unsafe (with regards to memory/lists/nodes/structs etc);
  200.  or - very difficult to use from Python.
  201.  Check the os and (amiga)path modules for things like file I/O,
  202.  path operations and other stuff.
  203.  
  204.  
  205. This module defines the following exception:
  206.  
  207.   error        - The exception that will be raised when an
  208.           error occurs related to dos.library. ('Doslib.error')
  209.           This is the same exception as the one from
  210.           the builtin Doslib module.
  211.  
  212.  
  213. +--------------------------------------+
  214. |                                      |
  215. |          DEFINED FUNCTIONS           |
  216. |                                      |
  217. +--------------------------------------+
  218.  
  219. As  this  module  imports everything from the Doslib module, see above what
  220. functions  are  provided.  Use the functions through this module, don't use
  221. the Doslib module directly.
  222.  
  223. There are some other functions implemented here as well:
  224.  
  225. touch(file [,time])
  226.     Changes the file's datestamp to the given time. Time is a Unix time value,
  227.     see the time module for more details (time.time). If omitted, the current
  228.     time is taken. If the specified file does not yet exist, it is created as
  229.     a zero-size file.
  230.  
  231. AddBuffers(drive, buffers)
  232.     A simple wrapper for c:addbuffers.
  233.  
  234. AssignAdd(name, target)
  235.     A simple wrapper for c:assign ADD.
  236.  
  237. AssignRemove(name)
  238.     A simple wrapper for c:assign REMOVE.
  239.  
  240.  
  241.  
  242. +--------------------------------------------+
  243. |                                            |
  244. |  DEFINED CONSTANTS (taken from dos/dos.h)  |
  245. |                                            |
  246. +--------------------------------------------+
  247.  
  248. - The break flags, SIGBREAKF_CTRL_C ..D..E.. SIGBREAKF_CTRL_F.
  249. - AmigaDOS file protection bits, including the `group' and `other' bits.
  250. - Flags and Format definitions for DateToStr and StrToDate.
  251. - Modes for SetConsoleMode(): MODE_CON and MODE_RAW.
  252.  
  253.  
  254. +--------------------------------------+
  255. |                                      |
  256. |          ARGPARSER CLASS             |
  257. |                                      |
  258. +--------------------------------------+
  259.  
  260. This  module  defines  the  ArgParser  class,  which  is an argument string
  261. parser.   It  can  be  used to parse ReadArgs() argument strings (the usual
  262. Amiga  style  for  command  lines,  all  CLI commands use it).  It works as
  263. follows:
  264.  
  265. p = Dos.ArgParser(template)
  266.  
  267.     Create new parser for the specified template.
  268.     template = ReadArgs template, like 'FROM/A/M,TO/A,QUIET/S'. 
  269.     
  270.     When parsing an argument string (see below) the type of the returned
  271.     Python value depends on the type of the argument in the template,
  272.     f.i. /N arguments will return an integer value.
  273.     `Multi'-options will ofcourse return a list.
  274.  
  275.     NOTE: /T (Switch Toggle) options are not supported.
  276.           (SystemError will be raised when you try to use /T)
  277.  
  278.     NOTE: ValueError will be raised when the template is considered
  279.           invalid.
  280.  
  281.  
  282. ** ArgParser objects have the following attributes:
  283.  
  284. defaults    - dictionary which contains the default values for each
  285.           template option which is not required (i.e. which is not
  286.           specified with /A switch). YOU MAY MODIFY THIS to change
  287.           the default options!!!
  288. template    - the template string. DO NOT MODIFY THIS! (use the `new'
  289.           member function to change the template)
  290. types        - internal type tuple. DO NOT MODIFY THIS! The structure is
  291.           as follows: ( (<template option>, <option type>), ... )
  292.           For instance when the template is 'FROM/A/M,TO/A,QUIET/S'
  293.           types will be (('FROM', ??), ('TO', ??), ('QUIET', ??)).
  294.           THE TYPE ENCODING IS PRIVATE, DO NOT TRY TO USE IT.
  295.  
  296.  
  297. ** ArgParser objects have the following member functions:
  298.  
  299. new(template)
  300.     modify the parser to use the new template
  301.  
  302. reset()
  303.     re-initialise the parser; reset defaults dictionary
  304.  
  305. parse(args)
  306.     The important one: parse the argument string args according to the
  307.     template of this ArgParser. Returns a dictionary containing the actual
  308.     arguments. The defaults dictionary is used to substitute default values
  309.     for unspecified arguments. Example:
  310.  
  311.     >>> p=Dos.ArgParser('FROM/A/M,TO/A,QUIET/S')
  312.     >>> p.defaults
  313.     {'QUIET': 0}
  314.     >>> p.types
  315.     (('FROM', 'A'), ('TO', 'X'), ('QUIET', 'S'))
  316.     >>> p.template
  317.     'FROM/A/M,TO/A,QUIET/S'
  318.     >>> p.parse('C:')
  319.     Doslib.error: You've forgotten an argument
  320.     >>> p.parse('C: ram:')
  321.     {'FROM': ['C:'], 'TO': 'ram:', 'QUIET': 0}
  322.     >>> r=p.parse('c:dir c:list c:copy TO RAM: quiet')
  323.     >>> print r
  324.     {'FROM': ['c:dir', 'c:list', 'c:copy'], 'TO': 'RAM:', 'QUIET': -1}
  325.     >>> for (o,t) in p.types: print 'Arg for',o,'is',r[o]
  326.     Arg for FROM is ['c:dir', 'c:list', 'c:copy']
  327.     Arg for TO is RAM:
  328.     Arg for QUIET is -1
  329.  
  330. Other member functions ARE PRIVATE.
  331.  
  332.   
  333.