This is a pre-production deployment of Warehouse, however changes made here WILL affect the production instance of PyPI.
Latest Version Dependencies status unknown Test status unknown Test coverage unknown
Project Description

supercli is a tiny Toolkit to quickly create readable, user-friendly CLI interfaces (+autocomplete).

(built on top of builtin argparse/logging modules)



This project has been built around tasks that I find myself repeating every time that I create a CLI interface. Aside from autocompletion-script generation, this project is less about providing features that are unavailable elsewhere than gluing together several existing options to quickly get you up and running.

__warning__ : this is still very much in alpha, and some arguments will change.









Features

argparse tweaks

  • Automatically generate ZSH autocompletion scripts (supports subarsers)
  • ReStructuredText syntax-highlighting within helplines
  • newlines, and ANSI colours can be used in helplines (on windows too)
  • enables logging (streamhandler) by default (reused if already exists)
  • builtin arguments (--help(-h), --verbose(-v), --very-verbose(-vv), --fullhelp)
  • builtin hidden arguments (--pdb,--devlog,--gen-autocomp,--default-parser)
  • extended set of logging-options can be enabled if needed (--logfile,--log-longfmt,--silent)
  • 1x metavar when multiple flags available for one command (-f, --file [METAVAR] instead of -f [METAVAR] --file [METAVAR])
  • argument flags are coloured white to standout from their descriptions.

logging tweaks

  • colour-coded logging (on windows too) (borrowed from unutbu and sorin on stackoverflow)
  • some useful logfilters (borrowed from unutbu and sorin on stackoverflow)
  • reuse existing loghandlers if already built in interactive python shells.
  • short string-based argument to quickly modify log-verbosity/logformat

Usage

QuickStart

This is all you need to do to create a CLI interface that matches the format above:

import supercli.argparse

parser = supercli.argparse.ArgumentParser(
            autocomp_cmd = 'myprogram',     ## name of command autocompletions are generated for
            description  = 'This descriptions can have `ReStructuredText` in it.',
            )
myprogram --gen-autocomp   ## create ZSH autocompletion script in current dir

argparse

This is just a collection of subclasses of the real argparse module, and the usage is mostly the same.

import supercli.argparse
from pygments.lexers      import HtmlLexer
from pygments.formatters  import Terminal256Formatter

parser = supercli.argparse.ArgumentParser(
            autocomp_cmd = 'myprogram',                ## name of command autocompletions are generated for
            description  = 'This descriptions can have `ReStructuredText` in it.',

            helpline_lexer     = HtmlLexer,            ## use a different lexer or formatter
            helpline_formatter = Terminal256Formatter, #  if you'd like

            extended_logopts   = True,                 ## enable flags for log options related to
                                                       #  logging to files

            developer_opts     = True,                 ## make `invisible` dev commands visible in
                                                       #  help menu for users

            loghandlers        = None,                 ## if logformat or loghandlers don't suit your needs
                                                       #  you can manage and pass your own formatted
                                                       #  loghandlers.
                                                       #  (-v|-vv) flags will stil work
        )

logging

If you’d like, you can also use the logging module independently of the argparse module. Once again, nothing really new or mindblowing here, this is purely convenience.

loglevel/logformat

The first argument, str_arg is a shorthand way of changing the loglevel and logformat.

import supercli.logging
import logging

logger = logging.getLogger(__name__)

## loglevel
supercli.logging.SetLog('')    ## log to stderr (using loglevel==logging.INFO by default)
                               #  each logrecord is prefixed by the datetime
supercli.logging.SetLog('i')   ## loglevel==logging.INFO
supercli.logging.SetLog('w')   ## loglevel==logging.WARNING
supercli.logging.SetLog('v')   ## loglevel==logging.DEBUG
supercli.logging.SetLog('vv')  ## loglevel==logging.DEBUG and disable all logfilters

## the long way
supercli.logging.SetLog( lv='INFO' )


## logformat
supercli.logging.SetLog('d')   ## (developer) instead of datetime, display __name__ and line-number
supercli.logging.SetLog('l')   ## each log-entry takes 2x lines (full import-path & func, time, lineno, etc)

## these can be combined
supercli.logging.SetLog('dv') ## (developer) and (verbose) flags are both active

logfile

99.9% of the time when I want to log to a file, I want to use a RotatingLogHandler. I’m guessing this is the case for most people, so it is the default behaviour.

import supercli.logging
import logging

logger = logging.getLogger(__name__)

supercli.logging.SetLog(
   lv           = 'INFO',
   logfile      = '/path/to/myfile.log',
   logstream    = False  ,               ## optionally, disable logging to STDERR
   logfile_size = 1000000,               ## =~8mb
   debug_mode   = False,                 ## this module is peppered with print() statements
                                         #  to assist in debugging. This displays them.
)

logfilters

LogFilters let you filter out logrecords based on some information. There are two logfilters in supercli.logging, but any logging.Filter subclass will work.

By default SetLog() is set up to use supercli.logging.BlackList as it’s filter. Each record is matched against the calling function’s import-path + function-name.

ex:

fnmatch.fnmatch( filter_value, '*{import_path}.{function_name}*' )
from   supercli.logging import SetLog, Blacklist
import logging

logger = logging.getLogger(__name__)

SetLog(
   lv             = 'INFO'               ,
   logfile        = '/path/to/myfile.log',
   logstream      = True                 ,
   filter_matches = ['sqliface.','chatty.module.func'],   ## filters records matching
                                                          #   '*sqliface.*',
                                                          #   '*chatty.module.func*'

   filter_type    = Blacklist,                            ## BlackList is the default
)

Todo

  • tests
  • bash autocompletion scripts
  • (zsh) completion types (_file,_netwkiface,…)
  • needs more flexible handling of ackward environments like maya. (I’m assuming all autodesk products have their own loghandlers for script-editors and the like)
  • make logging.WhiteList work like Blacklist works.
  • WhiteList and BlackList need to be able to be used together
  • Show a more generic use of command in picture..

Thanks

  • colorama authors for filling cmd.exe with colourful text, instead of the room with colourful language.
  • stackoverflow users unutbu and sorin for windows-colour/logfilter solutions.
Release History

Release History

0.0a3

This version

History Node

TODO: Figure out how to actually get changelog content.

Changelog content for this version goes here.

Donec et mollis dolor. Praesent et diam eget libero egestas mattis sit amet vitae augue. Nam tincidunt congue enim, ut porta lorem lacinia consectetur. Donec ut libero sed arcu vehicula ultricies a non tortor. Lorem ipsum dolor sit amet, consectetur adipiscing elit.

Show More

0.0a2

History Node

TODO: Figure out how to actually get changelog content.

Changelog content for this version goes here.

Donec et mollis dolor. Praesent et diam eget libero egestas mattis sit amet vitae augue. Nam tincidunt congue enim, ut porta lorem lacinia consectetur. Donec ut libero sed arcu vehicula ultricies a non tortor. Lorem ipsum dolor sit amet, consectetur adipiscing elit.

Show More

0.0a1

History Node

TODO: Figure out how to actually get changelog content.

Changelog content for this version goes here.

Donec et mollis dolor. Praesent et diam eget libero egestas mattis sit amet vitae augue. Nam tincidunt congue enim, ut porta lorem lacinia consectetur. Donec ut libero sed arcu vehicula ultricies a non tortor. Lorem ipsum dolor sit amet, consectetur adipiscing elit.

Show More

Download Files

Download Files

TODO: Brief introduction on what you do with files - including link to relevant help section.

File Name & Checksum SHA256 Checksum Help Version File Type Upload Date
supercli-0.0a3.tar.gz (25.3 kB) Copy SHA256 Checksum SHA256 Source Dec 10, 2016

Supported By

WebFaction WebFaction Technical Writing Elastic Elastic Search Pingdom Pingdom Monitoring Dyn Dyn DNS HPE HPE Development Sentry Sentry Error Logging CloudAMQP CloudAMQP RabbitMQ Heroku Heroku PaaS Kabu Creative Kabu Creative UX & Design Fastly Fastly CDN DigiCert DigiCert EV Certificate Rackspace Rackspace Cloud Servers DreamHost DreamHost Log Hosting