dircolors 0.0.4

Python library to colorize filenames in a terminal based on their type

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.

Distributions are built using flit and PEP 517 rather than setuptools (setup.py). Installing from PyPi using pip works as usual, flit is only needed for building sdists and wheels from git source.

Installation

Install with pip:

pip install dircolors

Install from source (should be used in a venv, don't run pip as root):

flit install
pip install .   # requires pip >= 19.0

Install from source in editable development mode (should be used in a venv):

flit install -s

On Arch Linux and its derivatives, you can install the python-dircolors AUR package.

Helper Makefile

This repo contains a makefile as a convenience that wraps some common development tasks. Possible make targets are:

• test (the default): run unit tests
• venv: set up a new python3 venv in the 'venv' directory and install an up-to-date pip, ipython, and everything from requirements-dev.txt (including flit). You should run source ./venv/bin/activate after make venv to enter the venv.
• lint: run pylint
• dist: build distribution sdist and wheel with flit
• clean: remove built dist packages and all __pycache__ files
• distclean: clean, plus remove the entire venv

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