Package: dircolors
pydircolors - color filenames for terminal displayDo you like file/directory listings in your terminal to be colorized? Do you like how GNU coreutils'lscommand does it? Want to incorporate that functionality into a Python application? Thenpydircolorsis the library for you!This library is currently in Alpha development stage, but I'm getting close to an initial release.System Requirementspydircolorsis 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-compatiblestat()syscalls. Notably,cmd.exeterminals on native Windows are not
supported, but Cygwin works.pydircolorsrequires Python 3.3 or newer. The main limitation is that thedir_fdandfollow_symlinkskeyword args toos.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 usingflitand 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.InstallationInstall with pip:pip install dircolorsInstall from source (should be used in a venv, don't run pip as root):flit install
pip install .   # requires pip >= 19.0Install from source in editable development mode (should be used in a venv):flit install -sOn Arch Linux and its derivatives, you can install thepython-dircolorsAUR package.Helper MakefileThis repo contains a makefile as a convenience that wraps some common development tasks. Possible
make targets are:test(the default): run unit testsvenv: 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 runsource ./venv/bin/activateaftermake venvto enter the venv.lint: run pylintdist: build distribution sdist and wheel with flitclean: remove built dist packages and all __pycache__ filesdistclean: clean, plus remove the entire venvUsageStart by creating aDircolorsobject and calling itsformat()method with the filename you want
to colorize.importdircolorsdc=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, thecwdkeyword argument looks for the filename relative to that directory.cwdcan be a string of the directory name, or an integer directory descriptor returned byos.open()on
the directory.Symlinks are intelligently supported too. Setfollow_symlinks=Trueto follow links and format the
link name like its target file. Setfollow_symlinks=False(the default) andshow_target=Trueto
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_targetIf you've already runos.stat()on a file, you can re-use the result to avoid extra syscall
overhead with theformat_mode()method.format_mode()accepts arbitrary text to format (which
need not actually be the filename) and the file mode, which can be anos.stat_resultobject (as
returned byos.stat()or an integer of representing thest_modefield.stat_result=os.stat('some_file')print(dc.format_mode('some_file',stat_result))print(dc.format_mode('a_link',0o0120777))Dircolors database sourcesBy default,Dircolorsobjects load from theLS_COLORSenvironment variable, just like GNUls.
A variety of functions to load from customLS_COLORSstrings or.dircolorsfiles 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 variabledc.load_from_lscolors('rs=0:di=01;34:')# load from an LS_COLORS stringdc.load_defaults()# use the defaults as generated by `dircolors -p`dc.load_from_dircolors('.dircolors')# load from a dircolors filenamedc.load_from_dircolors(open_file_obj)# load from an open file-like objectDocumentationFormal documentation is a TODO item. For now, this README provides basic usage and the docstrings indircolors.pyprovide
more details.Licensepydircolorsis released under the Apache 2.0 license. Copyright 2019 Allen Wild <allenwild93 at
gmail dot com>See the LICENSE.txt file for more information.TODOItems needed for a v0.1.0 release:Clean uppylsand add some argparse support. Also document it here.Add tests for the color formatting functionality rather than just loading data.Upload to PyPiItems needed for a v1.0.0 release:Sphinx documentationEnhancedpylsfunctionalityCommit to a stable API