Metadata-Version: 2.1
Name: dircolors
Version: 0.0.1
Summary: Python library to colorize and format file names based on type
Home-page: https://github.com/aswild/pydircolors
Author: Allen Wild
Author-email: allenwild93@gmail.com
License: Apache-2.0
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()`](https://docs.python.org/3/library/os.html#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.
        
        ```python
        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.
        
        ```python
        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.
        
        ```python
        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`](https://github.com/aswild/pydircolors/blob/master/dircolors/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
        
Platform: UNKNOWN
Classifier: Development Status :: 3 - Alpha
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.3
Classifier: Programming Language :: Python :: 3.4
Classifier: Programming Language :: Python :: 3.5
Classifier: Programming Language :: Python :: 3.6
Classifier: Programming Language :: Python :: 3.7
Classifier: Operating System :: POSIX
Classifier: Operating System :: POSIX :: Linux
Requires-Python: >=3.3
Description-Content-Type: text/markdown
