1# Copyright 2014 Altera Corporation. All Rights Reserved.
2# Author: John McGehee
3#
4# Licensed under the Apache License, Version 2.0 (the "License");
5# you may not use this file except in compliance with the License.
6# You may obtain a copy of the License at
7#
8#      http://www.apache.org/licenses/LICENSE-2.0
9#
10# Unless required by applicable law or agreed to in writing, software
11# distributed under the License is distributed on an "AS IS" BASIS,
12# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13# See the License for the specific language governing permissions and
14# limitations under the License.
15
16"""
17Example module that is tested in :py:class`pyfakefs.example_test.TestExample`.
18This demonstrates the usage of the
19:py:class`pyfakefs.fake_filesystem_unittest.TestCase` base class.
20
21The modules related to file handling are bound to the respective fake modules:
22
23>>> os     #doctest: +ELLIPSIS
24<pyfakefs.fake_os.FakeOsModule object...>
25>>> os.path     #doctest: +ELLIPSIS
26<pyfakefs.fake_path.FakePathModule object...>
27>>> shutil     #doctest: +ELLIPSIS
28<pyfakefs.fake_filesystem_shutil.FakeShutilModule object...>
29
30`open()` is an alias for `io.open()` and is bound to `FakeIoModule.open`.
31"""
32
33import glob
34import os
35import shutil
36
37try:
38    import scandir
39
40    has_scandir = True
41except ImportError:
42    scandir = None
43    has_scandir = False
44
45
46def create_file(path):
47    """Create the specified file and add some content to it.  Use the `open()`
48    built in function.
49
50    For example, the following file operations occur in the fake file system.
51    In the real file system, we would not even have permission
52    to write `/test`:
53
54    >>> os.path.isdir('/test')
55    False
56    >>> os.mkdir('/test')
57    >>> os.path.isdir('/test')
58    True
59    >>> os.path.exists('/test/file.txt')
60    False
61    >>> create_file('/test/file.txt')
62    >>> os.path.exists('/test/file.txt')
63    True
64    >>> with open('/test/file.txt') as f:
65    ...     f.readlines()
66    ["This is test file '/test/file.txt'.\\n", \
67'It was created using open().\\n']
68    """
69    with open(path, "w") as f:
70        f.write("This is test file '{0}'.\n".format(path))
71        f.write("It was created using open().\n")
72
73
74def delete_file(path):
75    """Delete the specified file.
76
77    For example:
78
79    >>> os.mkdir('/test')
80    >>> os.path.exists('/test/file.txt')
81    False
82    >>> create_file('/test/file.txt')
83    >>> os.path.exists('/test/file.txt')
84    True
85    >>> delete_file('/test/file.txt')
86    >>> os.path.exists('/test/file.txt')
87    False
88    """
89    os.remove(path)
90
91
92def path_exists(path):
93    """Return True if the specified file exists.
94
95    For example:
96
97    >>> path_exists('/test')
98    False
99    >>> os.mkdir('/test')
100    >>> path_exists('/test')
101    True
102    >>>
103    >>> path_exists('/test/file.txt')
104    False
105    >>> create_file('/test/file.txt')
106    >>> path_exists('/test/file.txt')
107    True
108    """
109    return os.path.exists(path)
110
111
112def get_glob(glob_path):
113    r"""Return the list of paths matching the specified glob expression.
114
115    For example:
116
117    >>> os.mkdir('/test')
118    >>> create_file('/test/file1.txt')
119    >>> create_file('/test/file2.txt')
120    >>> file_names = sorted(get_glob('/test/file*.txt'))
121    >>>
122    >>> import sys
123    >>> if sys.platform.startswith('win'):
124    ...     # Windows style path
125    ...     file_names == [r'/test\file1.txt', r'/test\file2.txt']
126    ... else:
127    ...     # UNIX style path
128    ...     file_names == ['/test/file1.txt', '/test/file2.txt']
129    True
130    """
131    return glob.glob(glob_path)
132
133
134def rm_tree(path):
135    """Delete the specified file hierarchy."""
136    shutil.rmtree(path)
137
138
139def scan_dir(path):
140    """Return a list of directory entries for the given path."""
141    if has_scandir:
142        return list(scandir.scandir(path))
143    return list(os.scandir(path))
144
145
146def file_contents(path):
147    """Return the contents of the given path as byte array."""
148    with open(path, "rb") as f:
149        return f.read()
150