Python API¶
Input types¶
shcol can columnize any item by simply relying on its string representation. The following example from an interactive Python session will illustrate that behavior:
>>> import shcol
>>> shcol.print_columnized(['spam', 0, 1.23, shcol.print_columnized])
spam 0 1.23 <function print_columnized at 0x039A8BB8>
Note that you are not restricted to use lists. You just need to pass an iterable object that contains the items to columnize. So these things are possible, too:
>>> shcol.print_columnized('abcdefg')
a b c d e f g
>>> shcol.print_columnized(xrange(10))
0 1 2 3 4 5 6 7 8 9
>>> shcol.print_columnized(n for n in xrange(10) if n >= 5)
5 6 7 8 9
shcol is also able to columnize dictionaries:
>>> inventory = {'Apples': 100, 'Bananas': 200}
>>> shcol.print_columnized(inventory)
Apples 100
Bananas 200
Changing spacing and line width¶
You can pass your own settings for the spacing between each item and for the output’s line width.
To do this, just use the appropriated keyword arguments:
>>> shcol.print_columnized(xrange(10), spacing=4)
0 1 2 3 4 5 6 7 8 9
>>> shcol.print_columnized(xrange(10), line_width=15)
0 2 4 6 8
1 3 5 7 9
How to use an additional separator¶
You maybe want to add an extra separator between the columns in some situations.
For this purpose, the extra_sep
-option was designed.
It takes a single character and can be used like this:
>>> shcol.print_columnized(xrange(10), extra_sep='|')
0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9
>>> shcol.print_columnized(xrange(10), extra_sep='|', line_width=20)
0 | 2 | 4 | 6 | 8
1 | 3 | 5 | 7 | 9
(New feature in development version - not yet released.)
Filtering input¶
Sometimes you want to filter your input according to specific criteria. For this, shcol supports filtering by wildcards (namely: ? and *).
This is how to pass different patterns as a filter:
>>> items = ['foo', 'bar', 'baz']
>>> shcol.print_columnized(items, pattern='f*')
foo
>>> shcol.print_columnized(items, pattern='b*')
bar baz
>>> shcol.print_columnized(items, pattern='*a*')
bar baz
>>> shcol.print_columnized(items, pattern='*r*')
bar
>>> shcol.print_columnized(items, pattern='ba?')
bar baz
>>> shcol.print_columnized(items, pattern='?a?')
bar baz
How to sort¶
shcol will do locale-dependent sorting via the sort_items
keyword.
Sorting can be done like this:
>>> shcol.print_columnized(['spam', 'ham', 'eggs'], sort_items=True)
eggs ham spam
>>> shcol.print_columnized(['späm', 'häm', 'äggs'], sort_items=True)
äggs häm späm
Please note that sorting items with non-ASCII characters will only work as intended if your system’s locale setting was set accordingly, i.e. in order to sort German Umlauts as shown above you should set a german locale.
Eliminating duplicates¶
If your input contains duplicates and you don’t want to have duplicates in your
columnized output then the make_unique
keyword is a good way to deal
with that.
When this feature is enabled then shcol will ignore subsequent occurrences of an item that already has been processed.
The effect of using make_unique
is illustrated by the following
example:
>>> items = ['spam', 'ham', 'spam', 'eggs', 'ham', 'eggs', 'spam']
>>> shcol.print_columnized(items, make_unique=True)
spam ham eggs
Note that make_unique
preserves the original order of the given items.
This differs from calling the Python standard library’s set()-constructor,
which makes no guarantees about the order of its result.
Printing directory contents¶
shcol includes a function called print_filenames() in order to print the content of a given path.
When called without arguments, it will print the filenames inside the current directory. For example, this is the result on the author’s Windows system when the current directory is C:\Python27:
>>> shcol.print_filenames()
DLLs include libs man python.exe README.txt tcl w9xpopen.exe
Doc Lib LICENSE.txt NEWS.txt pythonw.exe Scripts Tools
The same effect can be achieved from C:\ when passing the directory name:
>>> shcol.print_filenames('Python27')
DLLs include libs man python.exe README.txt tcl w9xpopen.exe
Doc Lib LICENSE.txt NEWS.txt pythonw.exe Scripts Tools
You may also pass wildcard characters (* and ?) in order to make use of shell globbing:
>>> shcol.print_filenames('Py*')
pypy26 Python27 Python34
>>> shcol.print_filenames('Py*2?')
pypy26 Python27
>>> shcol.print_filenames('Python27\*.txt')
LICENSE.txt NEWS.txt README.txt
Note that print_columnized() is used under the hood to do the actual
columnizing, so all of its options (such as spacing
,
line_width
, ...) are available as well:
>>> shcol.print_filenames('Python27', spacing=5, line_width=50)
DLLs LICENSE.txt README.txt
Doc man Scripts
include NEWS.txt tcl
Lib python.exe Tools
libs pythonw.exe w9xpopen.exe
The print_sorted()-shortcut¶
For convenience, the idiom print_columnized(items, sort_items=True) can be replaced with print_sorted(items). As known from print_filenames(), all additional options are passed to print_columnized() to be interpreted there.
The following examples show some use cases where this function is used to inspect objects in a Python interpreter session:
>>> shcol.print_sorted(dir(shcol), line_width=50)
__author__ __path__ helpers
__builtins__ __version__ highlevel
__doc__ cli print_columnized
__file__ columnize print_filenames
__license__ config print_sorted
__name__ core
__package__ formatters
>>> shcol.print_sorted(dir(shcol), pattern='print*')
print_columnized print_filenames print_sorted
>>> import os
>>> shcol.print_sorted(os.environ, pattern='*PROG*')
COMMONPROGRAMFILES C:\Program Files (x86)\Common Files
COMMONPROGRAMFILES(X86) C:\Program Files (x86)\Common Files
COMMONPROGRAMW6432 C:\Program Files\Common Files
PROGRAMDATA C:\ProgramData
PROGRAMFILES C:\Program Files (x86)
PROGRAMFILES(X86) C:\Program Files (x86)
PROGRAMW6432 C:\Program Files