Mercurial > repos > shellac > guppy_basecaller

comparison env/lib/python3.7/site-packages/scandir-1.10.0-py3.7.egg-info/PKG-INFO @ 0:26e78fe6e8c4 draft

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
"planemo upload commit c699937486c35866861690329de38ec1a5d9f783"
author shellac
date Sat, 02 May 2020 07:14:21 -0400
parents
children
comparison
equal deleted inserted replaced
-1:000000000000 0:26e78fe6e8c4
1 Metadata-Version: 1.1
2 Name: scandir
3 Version: 1.10.0
4 Summary: scandir, a better directory iterator and faster os.walk()
5 Home-page: https://github.com/benhoyt/scandir
6 Author: Ben Hoyt
7 Author-email: benhoyt@gmail.com
8 License: New BSD License
9 Description:
10 scandir, a better directory iterator and faster os.walk()
11 =========================================================
12
13 .. image:: https://img.shields.io/pypi/v/scandir.svg
14 :target: https://pypi.python.org/pypi/scandir
15 :alt: scandir on PyPI (Python Package Index)
16
17 .. image:: https://travis-ci.org/benhoyt/scandir.svg?branch=master
18 :target: https://travis-ci.org/benhoyt/scandir
19 :alt: Travis CI tests (Linux)
20
21 .. image:: https://ci.appveyor.com/api/projects/status/github/benhoyt/scandir?branch=master&svg=true
22 :target: https://ci.appveyor.com/project/benhoyt/scandir
23 :alt: Appveyor tests (Windows)
24
25
26 ``scandir()`` is a directory iteration function like ``os.listdir()``,
27 except that instead of returning a list of bare filenames, it yields
28 ``DirEntry`` objects that include file type and stat information along
29 with the name. Using ``scandir()`` increases the speed of ``os.walk()``
30 by 2-20 times (depending on the platform and file system) by avoiding
31 unnecessary calls to ``os.stat()`` in most cases.
32
33
34 Now included in a Python near you!
35 ----------------------------------
36
37 ``scandir`` has been included in the Python 3.5 standard library as
38 ``os.scandir()``, and the related performance improvements to
39 ``os.walk()`` have also been included. So if you're lucky enough to be
40 using Python 3.5 (release date September 13, 2015) you get the benefit
41 immediately, otherwise just
42 `download this module from PyPI <https://pypi.python.org/pypi/scandir>`_,
43 install it with ``pip install scandir``, and then do something like
44 this in your code:
45
46 .. code-block:: python
47
48 # Use the built-in version of scandir/walk if possible, otherwise
49 # use the scandir module version
50 try:
51 from os import scandir, walk
52 except ImportError:
53 from scandir import scandir, walk
54
55 `PEP 471 <https://www.python.org/dev/peps/pep-0471/>`_, which is the
56 PEP that proposes including ``scandir`` in the Python standard library,
57 was `accepted <https://mail.python.org/pipermail/python-dev/2014-July/135561.html>`_
58 in July 2014 by Victor Stinner, the BDFL-delegate for the PEP.
59
60 This ``scandir`` module is intended to work on Python 2.7+ and Python
61 3.4+ (and it has been tested on those versions).
62
63
64 Background
65 ----------
66
67 Python's built-in ``os.walk()`` is significantly slower than it needs to be,
68 because -- in addition to calling ``listdir()`` on each directory -- it calls
69 ``stat()`` on each file to determine whether the filename is a directory or not.
70 But both ``FindFirstFile`` / ``FindNextFile`` on Windows and ``readdir`` on Linux/OS
71 X already tell you whether the files returned are directories or not, so
72 no further ``stat`` system calls are needed. In short, you can reduce the number
73 of system calls from about 2N to N, where N is the total number of files and
74 directories in the tree.
75
76 In practice, removing all those extra system calls makes ``os.walk()`` about
77 **7-50 times as fast on Windows, and about 3-10 times as fast on Linux and Mac OS
78 X.** So we're not talking about micro-optimizations. See more benchmarks
79 in the "Benchmarks" section below.
80
81 Somewhat relatedly, many people have also asked for a version of
82 ``os.listdir()`` that yields filenames as it iterates instead of returning them
83 as one big list. This improves memory efficiency for iterating very large
84 directories.
85
86 So as well as a faster ``walk()``, scandir adds a new ``scandir()`` function.
87 They're pretty easy to use, but see "The API" below for the full docs.
88
89
90 Benchmarks
91 ----------
92
93 Below are results showing how many times as fast ``scandir.walk()`` is than
94 ``os.walk()`` on various systems, found by running ``benchmark.py`` with no
95 arguments:
96
97 ==================== ============== =============
98 System version Python version Times as fast
99 ==================== ============== =============
100 Windows 7 64-bit 2.7.7 64-bit 10.4
101 Windows 7 64-bit SSD 2.7.7 64-bit 10.3
102 Windows 7 64-bit NFS 2.7.6 64-bit 36.8
103 Windows 7 64-bit SSD 3.4.1 64-bit 9.9
104 Windows 7 64-bit SSD 3.5.0 64-bit 9.5
105 Ubuntu 14.04 64-bit 2.7.6 64-bit 5.8
106 Mac OS X 10.9.3 2.7.5 64-bit 3.8
107 ==================== ============== =============
108
109 All of the above tests were done using the fast C version of scandir
110 (source code in ``_scandir.c``).
111
112 Note that the gains are less than the above on smaller directories and greater
113 on larger directories. This is why ``benchmark.py`` creates a test directory
114 tree with a standardized size.
115
116
117 The API
118 -------
119
120 walk()
121 ~~~~~~
122
123 The API for ``scandir.walk()`` is exactly the same as ``os.walk()``, so just
124 `read the Python docs <https://docs.python.org/3.5/library/os.html#os.walk>`_.
125
126 scandir()
127 ~~~~~~~~~
128
129 The full docs for ``scandir()`` and the ``DirEntry`` objects it yields are
130 available in the `Python documentation here <https://docs.python.org/3.5/library/os.html#os.scandir>`_.
131 But below is a brief summary as well.
132
133 scandir(path='.') -> iterator of DirEntry objects for given path
134
135 Like ``listdir``, ``scandir`` calls the operating system's directory
136 iteration system calls to get the names of the files in the given
137 ``path``, but it's different from ``listdir`` in two ways:
138
139 * Instead of returning bare filename strings, it returns lightweight
140 ``DirEntry`` objects that hold the filename string and provide
141 simple methods that allow access to the additional data the
142 operating system may have returned.
143
144 * It returns a generator instead of a list, so that ``scandir`` acts
145 as a true iterator instead of returning the full list immediately.
146
147 ``scandir()`` yields a ``DirEntry`` object for each file and
148 sub-directory in ``path``. Just like ``listdir``, the ``'.'``
149 and ``'..'`` pseudo-directories are skipped, and the entries are
150 yielded in system-dependent order. Each ``DirEntry`` object has the
151 following attributes and methods:
152
153 * ``name``: the entry's filename, relative to the scandir ``path``
154 argument (corresponds to the return values of ``os.listdir``)
155
156 * ``path``: the entry's full path name (not necessarily an absolute
157 path) -- the equivalent of ``os.path.join(scandir_path, entry.name)``
158
159 * ``is_dir(*, follow_symlinks=True)``: similar to
160 ``pathlib.Path.is_dir()``, but the return value is cached on the
161 ``DirEntry`` object; doesn't require a system call in most cases;
162 don't follow symbolic links if ``follow_symlinks`` is False
163
164 * ``is_file(*, follow_symlinks=True)``: similar to
165 ``pathlib.Path.is_file()``, but the return value is cached on the
166 ``DirEntry`` object; doesn't require a system call in most cases;
167 don't follow symbolic links if ``follow_symlinks`` is False
168
169 * ``is_symlink()``: similar to ``pathlib.Path.is_symlink()``, but the
170 return value is cached on the ``DirEntry`` object; doesn't require a
171 system call in most cases
172
173 * ``stat(*, follow_symlinks=True)``: like ``os.stat()``, but the
174 return value is cached on the ``DirEntry`` object; does not require a
175 system call on Windows (except for symlinks); don't follow symbolic links
176 (like ``os.lstat()``) if ``follow_symlinks`` is False
177
178 * ``inode()``: return the inode number of the entry; the return value
179 is cached on the ``DirEntry`` object
180
181 Here's a very simple example of ``scandir()`` showing use of the
182 ``DirEntry.name`` attribute and the ``DirEntry.is_dir()`` method:
183
184 .. code-block:: python
185
186 def subdirs(path):
187 """Yield directory names not starting with '.' under given path."""
188 for entry in os.scandir(path):
189 if not entry.name.startswith('.') and entry.is_dir():
190 yield entry.name
191
192 This ``subdirs()`` function will be significantly faster with scandir
193 than ``os.listdir()`` and ``os.path.isdir()`` on both Windows and POSIX
194 systems, especially on medium-sized or large directories.
195
196
197 Further reading
198 ---------------
199
200 * `The Python docs for scandir <https://docs.python.org/3.5/library/os.html#os.scandir>`_
201 * `PEP 471 <https://www.python.org/dev/peps/pep-0471/>`_, the
202 (now-accepted) Python Enhancement Proposal that proposed adding
203 ``scandir`` to the standard library -- a lot of details here,
204 including rejected ideas and previous discussion
205
206
207 Flames, comments, bug reports
208 -----------------------------
209
210 Please send flames, comments, and questions about scandir to Ben Hoyt:
211
212 http://benhoyt.com/
213
214 File bug reports for the version in the Python 3.5 standard library
215 `here <https://docs.python.org/3.5/bugs.html>`_, or file bug reports
216 or feature requests for this module at the GitHub project page:
217
218 https://github.com/benhoyt/scandir
219
220 Platform: UNKNOWN
221 Classifier: Development Status :: 5 - Production/Stable
222 Classifier: Intended Audience :: Developers
223 Classifier: Operating System :: OS Independent
224 Classifier: License :: OSI Approved :: BSD License
225 Classifier: Programming Language :: Python
226 Classifier: Topic :: System :: Filesystems
227 Classifier: Topic :: System :: Operating System
228 Classifier: Programming Language :: Python
229 Classifier: Programming Language :: Python :: 2
230 Classifier: Programming Language :: Python :: 2.7
231 Classifier: Programming Language :: Python :: 3
232 Classifier: Programming Language :: Python :: 3.4
233 Classifier: Programming Language :: Python :: 3.5
234 Classifier: Programming Language :: Python :: 3.6
235 Classifier: Programming Language :: Python :: 3.7
236 Classifier: Programming Language :: Python :: Implementation :: CPython