Scripts:
[blender.git] / source / blender / python / api2_2x / doc / Sys.py
1 # Blender.sys module
2
3 """
4 The Blender.sys submodule.
5
6 sys
7 ===
8
9 B{New}: L{exists}, L{makename}, L{join}.
10
11 This module provides a minimal set of helper functions and data.  Its purpose
12 is to avoid the need for the standard Python module 'os', in special 'os.path',
13 though it is only meant for the simplest cases.
14
15 Example::
16
17   import Blender
18
19   filename = ""
20   def f(name): # file selector callback
21     global filename
22     filename = name
23
24   Blender.Window.FileSelector(f)
25
26   if filename:
27     print 'basename:', Blender.sys.basename(filename)
28     print 'dirname:',  Blender.sys.dirname(filename)
29     print 'splitext:', Blender.sys.splitext(filename)
30
31   # what would basename(splitext(filename)[0]) print?
32
33 @type sep: char
34 @var sep: the platform-specific dir separator for this Blender: '/'
35     everywhere, except on Win systems, that use '\\'. 
36 @type dirsep: char
37 @var dirsep: same as L{sep}.
38 @type progname: string
39 @var progname: the Blender executable (argv[0]).
40
41 @attention: The module is called sys, not Sys.
42 """
43
44 def basename (path):
45   """
46   Get the base name (filename stripped from dir info) of 'path'.
47   @type path: string
48   @param path: a path name
49   @rtype: string
50   @return: the base name
51   """
52
53 def dirname (path):
54   """
55   Get the dir name (dir path stripped from filename) of 'path'.
56   @type path: string
57   @param path: a path name
58   @rtype: string
59   @return: the dir name
60   """
61
62 def join (dir, file):
63   """
64   Join the given dir and file paths, using the proper separator for each
65   platform.
66   @type dir: string
67   @type file: string
68   @param dir: the dir name, like returned from L{dirname}.
69   @param file: the bare filename, like returned from L{basename}.
70   @rtype: string
71   @return: the resulting filename.
72   @warn: this simple function isn't intended to be a complete replacement for
73      the standard os.path.join() one, which handles more general cases.
74   """
75
76 def splitext (path):
77   """
78   Split 'path' into (root, ext), where 'ext' is a file extension.
79   @type path: string
80   @param path: a path name
81   @rtype: list with two strings
82   @return: (root, ext)
83   """
84
85 def makename (path = "Blender.Get('filename')", ext = "", strip = 0):
86   """
87   Remove extension from 'path', append extension 'ext' (if given)
88   to the result and return it.  If 'strip' is non-zero, also remove
89   dirname from path.
90
91   Example::
92     import Blender
93     from Blender.sys import *
94     print makename('/path/to/myfile.txt','.abc', 1) # returns 'myfile.abc'
95
96     print makename('/path/to/myfile.obj', '-01.obj') # '/path/to/myfile-01.obj'
97
98     print makename('/path/to/myfile.txt', strip = 1) # 'myfile'
99
100     # note that:
101     print makename(ext = '.txt')
102     # is equivalent to:
103     print sys.splitext(Blender.Get('filename'))[0]) + '.txt'
104
105   @type path: string
106   @param path: a path name or Blender.Get('filename'), if not given.
107   @type ext: string
108   @param ext: an extension to append.  For flexibility, a dot ('.') is
109       not automatically included.
110   @rtype: string
111   @return: the resulting string
112   """
113
114 def exists(path):
115   """
116   Tell if the given pathname (file or dir) exists.
117   @rtype: bool
118   @return: 1 if 'path' exists, 0 otherwise.
119   """
120
121 def time ():
122   """
123   Get the current time in seconds since a fixed value.  Successive calls to
124   this function are garanteed to return values greater than the previous call.
125   @rtype: float
126   @return: the elapsed time in seconds.
127   """