1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342
|
# -*- coding: utf-8 -*-
# Note: this module fails doctesting
"""
This module provides code for producing folder structure strings for directories.
Currently, the only tool here is `seedir()`, the primary function of the
package `seedir`. This returns or prints the folder structure for a given path.
The main algorithm for determining the folder structure string is within the
<code>seedir.folderstructure.FolderStructure</code> class.
"""
import os
import pathlib
from seedir.folderstructure import PathlibStructure, RealDirStructure
def _parse_path(path):
'''Helper function added to parse the input to `seedir.realdir.seedir()`.
Detects strings (paths) or pathlib objects.'''
if isinstance(path, str):
path = os.path.abspath(os.path.expanduser(path))
elif isinstance(path, pathlib.Path):
path = path.expanduser().resolve()
else:
raise TypeError(f"Can only parse str or pathlib.Path, not {type(path)}.")
return path
def seedir(path=None, style='lines', printout=True, indent=2, uniform=None,
anystart=None, anyend=None, depthlimit=None, itemlimit=None,
beyond=None, first=None, sort=False, sort_reverse=False,
sort_key=None, include_folders=None, exclude_folders=None,
include_files=None, exclude_files=None, regex=False, mask=None,
formatter=None, sticky_formatter=False,
acceptable_listdir_errors=PermissionError,
denied_string=' [ACCESS DENIED]', **kwargs):
'''
Primary function of the seedir package: generate folder trees for
computer directories.
## EXAMPLES
```
>>> import seedir as sd
```
Make a basic tree diagram:
```
>>> c = 'path/to/doc'
>>> sd.seedir(c)
doc/
├─_static/
│ ├─embedded/
│ │ ├─deep_file
│ │ └─very/
│ │ └─deep/
│ │ └─folder/
│ │ └─very_deep_file
│ └─less_deep_file
├─about.rst
├─conf.py
└─index.rst
```
Select different styles for the tree:
```
>>> sd.seedir(c, style='dash')
doc/
|-_static/
| |-embedded/
| | |-deep_file
| | |-very/
| | |-deep/
| | |-folder/
| | |-very_deep_file
| |-less_deep_file
|-about.rst
|-conf.py
|-index.rst
```
Sort the folder contents, separting folders and files:
```
>>> sd.seedir(c, sort=True, first='files')
doc/
├─about.rst
├─conf.py
├─index.rst
└─_static/
├─less_deep_file
└─embedded/
├─deep_file
└─very/
└─deep/
└─folder/
└─very_deep_file
```
Limit the folder depth or items included:
```
>>> sd.seedir(c, depthlimit=2, itemlimit=1)
doc/
├─_static/
│ ├─embedded/
│ └─less_deep_file
└─about.rst
```
Include or exclude specific items (with or without regular expressions):
```
>>> sd.seedir(c, exclude_folders='_static')
doc/
├─about.rst
├─conf.py
└─index.rst
```
Parameters
----------
path : str, pathlib.Path, or None, optional
System path of a directory. If None, current working directory is
used. The path can be either a string path or a pathlib object.
In both cases, the path is converted to an absolute path, and the
tilde (~) is expanded.
style : 'lines', 'dash', 'arrow', 'spaces', 'plus', or 'emoji', optional
Style to use. The default is `'lines'`. A style determines the set
of characters ("tokens") used to represent the base structure of
the directory (e.g. which items belong to which folders, when items
are the last member of a folder, etc.). The actual tokens being used
by each style can be viewed with `seedir.printing.get_styleargs()`.
printout : bool, optional
Print the folder structure in the console. The default is `True`. When
`False`, the folder diagram is returned as a string.
indent : int (>= 0), optional
Number of spaces separating items from their parent folder.
The default is `2`.
uniform : str or None, optional
Characters to use for all tokens when creating the tree diagram.
The default is `None`. When not `None`, the extend, space, split, and
final tokens are replaced with `uniform` (the `'spaces'` style is
essentially `uniform = ' '`).
anystart : str or None, optional
Characters to prepend before any item (i.e. folder or file). The
default is `None`. Specific starts for folders and files can be
specified (see `**kwargs`).
anyend : str or None, optional
Characters to append after any item (i.e. folder or file). The
default is `None`. Specific ends for folders and files can be
specified (see `**kwargs`).
depthlimit : int or None, optional
Limit the depth of folders to traverse. Folders at the `depthlimit` are
included, but their contents are not shown (with the exception of the
beyond parameter being specified). The default is `None`, which can
cause exceptionally long runtimes for deep or extensive directories.
itemlimit : int or None, optional
Limit the number of items in a directory to show. Items beyond the
`itemlimit` can be expressed using the `beyond` parameter. The files and
folders left out are determined by the sorting parameters
(`sort`, `sort_reverse`, `sort_key`). The default is `None`.
beyond : str ('ellipsis', 'content' or a string starting with an underscore) or None, optional
String to indicate directory contents beyond the `itemlimit` or the
`depthlimit`. The default is `None`. Options are: `'ellipsis'` (`'...'`),
`'content'` or `'contents'` (the number of files and folders beyond), or
a string starting with `'_'` (everything after the leading underscore
will be returned)
first : 'files', 'folders', or None, optional
Sort the directory so that either files or folders appear first.
The default is `None`.
sort : bool, optional
Sort the directory. With no other specifications, the sort will be a
simple alphabetical sort of the item names, but this can be altered
with the `first`, `sort_reverse`, and `sort_key parameters`.
The default is `False`.
sort_reverse : bool, optional
Reverse the sorting determined by `sort` or `sort_key`.
The default is `False`.
sort_key : function, optional
Key to use for sorting file or folder names, akin to the `key` parameter
of the builtin `sorted()` or `list.sort()`. The function should take a
string as an argument. The default is `None`.
include_folders, exclude_folders, include_files, exclude_files : str, list-like, or None, optional
Folder / file names to include or exclude. The default is `None`. By
default, these are interpreted literally. Pass `regex=True` for
using regular expressions.
regex : bool, optional
Interpret the strings of include/exclude file/folder arguments as
regular expressions. The default is `False`.
mask : function, optional
Function for filtering items. Absolute paths of each individual item
are passed to the `mask` function. If `True` is returned, the
item is kept. The default is `None`. The type of the object
passed to `mask` corresponds with that passed as input:
`str` or `pathlib.Path`.
formatter : function, optional
Function for customizing the directory printing logic and style
based on specific folders & files. When passed, the formatter
is called on each item in the file tree, and the current arguments
are updated based what is returned.
The formatter function should accept a system path as a
single argument (either relative or absolute, depending on what is passed
to the `path` argument), and it should return either a dictionary or None.
The dictionary should have names of arguments as keys and their respective
setting as values.
The following options can meaningfully be toggled by passing a formatter
function: `depthlimit`, `itemlimit`, `beyond`, `first`, `sort`, `sort_reverse`,
`sort_key`, `include_folders`, `regex`, `mask`, as well as any seedir token
keywords (`extend`, `space`, `split`, `final`, `folderstart`, `filestart`,
`folderend`, `fileend`).
Note that in version 0.3.0, formatter could only be used to update
the style tokens. It can now be used to udpate those as well as the other
arguments listed above.
If None is returned by formatter, the tokens will be set by `style`.
Note that items exlcuded by the inclusion/exclusion arguments (or the
`mask`) *will not* be seen by formatter. Similarly, any folder tree
entries created by the `beyond` argument *will not* be seen by formatter.
The type of the object passed to `formatter` corresponds with that
passed as input: `str` or `pathlib.Path`.
sticky_formatter : bool, optional
When True, updates to argumnts made by the `formatter` (see above)
will be permanent. Thus, if arguments are updated when the `formatter`
is called on a folder, its children will (recursively) inherit
those new arguments.
acceptable_listdir_errors : Exception, tuple, or None
**New in v0.5.0**
Set errors which, when raised when listing the contents of a folder,
do not halt traversal. This parameter was added to allow
folders to be skipped when a `PermissionError` is raised. For folders
which raise an acceptable error, an additional string is added to their
entry in the diagram (see `denied_string`).
Providing one Exception causes only that type of Exception to be ignored.
Multiple Exception types can be handled by passing mutple Exceptions
as a tuple. Pass `None` to not allow any Exceptions (in this case,
an error is raised).
Exception types which are not provided will still be raised.
The default is `PermissionError`, which will skip folders
for which the caller does not have permissions to access.
denied_string : str
String tag to signify that a folder was not able to be traversed
due to one of the `acceptable_listdir_errors` being raised. This
is a string added after the folder name (and `folderend`) strings.
The default is `" [ACCESS DENIED]"`.
**kwargs : str
Specific tokens to use for creating the file tree diagram. The tokens
use by each builtin style can be seen with `seedir.printing.get_styleargs()`.
Valid options are `extend` (characters to show the extension of a directory
while its children are traversed), `space` (character to provide the
correct indentation of an item when some of its parent / grandparent
directories are completely traversed), `split` (characters to show a
folder or file within a directory, with more items following),
`final` (characters to show a folder or file within a directory,
with no more items following), `folderstart` (characters to prepend
before any folder), `filestart` (characters to preppend before any
file), `folderend` (characters to append after any folder), and
`fileend` (characters to append after any file). The following shows
the default tokens for the `'lines'` style:
>>> import seedir as sd
>>> sd.get_styleargs('lines')
{'split': '├─', 'extend': '│ ', 'space': ' ', 'final': '└─', 'folderstart': '', 'filestart': '', 'folderend': '/', 'fileend': ''}
All default style tokens are 2 character strings, except for
the file/folder start/end tokens. Style tokens from `**kwargs` are not
affected by the indent parameter. The `uniform`, `anystart`, and
`anyend` parameters can be used to affect multiple style tokens.
Notes
-------
The parameter `slash` was deprecated in 0.5.0. Pass `folderend` as
an additional keyword argument instead.
Returns
-------
s (str) or None
The tree diagram (as a string) or `None` if `prinout = True`, in which
case the tree diagram is printed in the console.
'''
if path is None:
path = os.getcwd()
path = _parse_path(path)
# call
args = dict(style=style,
printout=printout,
indent=indent,
uniform=uniform,
anystart=anystart,
anyend=anyend,
depthlimit=depthlimit,
itemlimit=itemlimit,
beyond=beyond,
first=first,
sort=sort,
sort_reverse=sort_reverse,
sort_key=sort_key,
include_folders=include_folders,
exclude_folders=exclude_folders,
include_files=include_files,
exclude_files=exclude_files,
regex=regex,
mask=mask,
formatter=formatter,
sticky_formatter=sticky_formatter,
acceptable_listdir_errors=acceptable_listdir_errors,
denied_string=denied_string,
**kwargs)
structure = PathlibStructure() if isinstance(path, pathlib.Path) else RealDirStructure()
return structure(path, **args)
|