9792d3fd278feabc788bea0f1466da0af8562ebf
[blender-staging.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}.
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 splitext (path):
63   """
64   Split 'path' into (root, ext), where 'ext' is a file extension.
65   @type path: string
66   @param path: a path name
67   @rtype: list with two strings
68   @return: (root, ext)
69   """
70
71 def makename (path = "Blender.Get('filename')", ext = "", strip = 0):
72   """
73   Remove extension from 'path', append extension 'ext' (if given)
74   to the result and return it.  If 'strip' is non-zero, also remove
75   dirname from path.
76
77   Example::
78     import Blender
79     from Blender.sys import *
80     print makename('/path/to/myfile.txt','.abc', 1) # returns 'myfile.abc'
81
82     print makename('/path/to/myfile.obj', '-01.obj') # '/path/to/myfile-01.obj'
83
84     print makename('/path/to/myfile.txt', strip = 1) # 'myfile'
85
86     # note that:
87     print makename(ext = '.txt')
88     # is equivalent to:
89     print sys.splitext(Blender.Get('filename'))[0]) + '.txt'
90
91   @type path: string
92   @param path: a path name or Blender.Get('filename'), if not given.
93   @type ext: string
94   @param ext: an extension to append.  For flexibility, a dot ('.') is
95       not automatically included.
96   @rtype: string
97   @return: the resulting string
98   """
99
100 def exists(path):
101   """
102   Tell if the given pathname (file or dir) exists.
103   @rtype: bool
104   @return: 1 if 'path' exists, 0 otherwise.
105   """
106
107 def time ():
108   """
109   Get the current time in seconds since a fixed value.  Successive calls to
110   this function are garanteed to return values greater than the previous call.
111   @rtype: float
112   @return: the elapsed time in seconds.
113   """