Python library to colorize and format file names based on type
Project description
pydircolors - color filenames for terminal display
Do you like file/directory listings in your terminal to be colorized? Do you like how GNU coreutils'
ls
command does it? Want to incorporate that functionality into a Python application? Then
pydircolors
is the library for you!
This library is currently in Alpha development stage, but I'm getting close to an initial release.
System Requirements
pydircolors
is intended for console use on POSIX-like systems. It's developed on Linux, but should
work in any terminal that supports xterm-style 16 color escape sequences and environments with
POSIX-compatible stat()
syscalls. Notably, cmd.exe
terminals on native Windows are not
supported, but Cygwin works.
pydircolors
requires Python 3.3 or newer. The main limitation is that the dir_fd
and
follow_symlinks
keyword args to os.stat()
are used, which were added in Python 3.3. It'd be possible to add support for older versions
(including Python 2.7) with compatibility shims. If you ask nicely, I'll a) be overjoyed that
someone's actually using this library, and b) will consider adding that functionality.
Usage
Start by creating a Dircolors
object and calling its format()
method with the filename you want
to colorize.
import dircolors
dc = dircolors.Dircolors()
print(dc.format('README.md'))
print(dc.format('dist/pydircolors.tar.gz')
print(dc.format('pydircolors.tar.gz', cwd='dist'))
As seen above, the cwd
keyword argument looks for the filename relative to that directory. cwd
can be a string of the directory name, or an integer directory descriptor returned by os.open()
on
the directory.
Symlinks are intelligently supported too. Set follow_symlinks=True
to follow links and format the
link name like its target file. Set follow_symlinks=False
(the default) and show_target=True
to
print the link name, colored like a link, an ASCII arrow (->
), and the link target, formatted
accordingly.
>>> print(dc.format('a_link', show_target=True))
a_link -> link_target
If you've already run os.stat()
on a file, you can re-use the result to avoid extra syscall
overhead with the format_mode()
method. format_mode()
accepts arbitrary text to format (which
need not actually be the filename) and the file mode, which can be an os.stat_result
object (as
returned by os.stat()
or an integer of representing the st_mode
field.
stat_result = os.stat('some_file')
print(dc.format_mode('some_file', stat_result))
print(dc.format_mode('a_link', 0o0120777))
Dircolors database sources
By default, Dircolors
objects load from the LS_COLORS
environment variable, just like GNU ls
.
A variety of functions to load from custom LS_COLORS
strings or .dircolors
files are available
as well. All load functions will clear the currently loaded database, even if they fail to load any
useful data.
dc.load_from_environ() # load from the LS_COLORS environment variable (the default)
dc.load_from_environ(env_var_name) # load from a different environment variable
dc.load_from_lscolors('rs=0:di=01;34:') # load from an LS_COLORS string
dc.load_defaults() # use the defaults as generated by `dircolors -p`
dc.load_from_dircolors('.dircolors') # load from a dircolors filename
dc.load_from_dircolors(open_file_obj) # load from an open file-like object
Documentation
Formal documentation is a TODO item. For now, this README provides basic usage and the docstrings in
dircolors.py
provide
more details.
License
pydircolors
is released under the Apache 2.0 license. Copyright 2019 Allen Wild <allenwild93 at
gmail dot com>
See the LICENSE.txt file for more information.
TODO
Items needed for a v0.1.0 release:
- Clean up
pyls
and add some argparse support. Also document it here. - Add tests for the color formatting functionality rather than just loading data.
- Upload to PyPi
Items needed for a v1.0.0 release:
- Sphinx documentation
- Enhanced
pyls
functionality - Commit to a stable API
Project details
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Hashes for dircolors-0.0.1-py3-none-any.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 8562f5de73853c11359e5f7c81c6b976455edb60fba4cbaca6a82c52caf5c5b6 |
|
MD5 | 5502c3d9de98c16e3b3d3212d65ba33b |
|
BLAKE2b-256 | e13914f6ddab4ba2fb4f66f069bfe1255c4898e5377dc894f841911c9bdfa24b |