root/config.py

# encoding: UTF-8
# Copyright (C) 2007, Stefan Schwarzer
#
# Permission is hereby granted, free of charge, to any person
# obtaining a copy of this software and associated documentation files
# (the "Software"), to deal in the Software without restriction,
# including without limitation the rights to use, copy, modify, merge,
# publish, distribute, sublicense, and/or sell copies of the Software,
# and to permit persons to whom the Software is furnished to do so,
# subject to the following conditions:
#
# The above copyright notice and this permission notice shall be
# included in all copies or substantial portions of the Software.
#
# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
# EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
# MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
# NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS
# BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN
# ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
# CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
# SOFTWARE.

"""
Configure the application.
"""

import sys


MAN_PAGE = """\
NAME

  Websourcebrowser - conveniently browse source code with a webbrowser

SYNOPSIS

  wsbrowser [options]

  The name of the executable is wsbrowser on Posix and wsbrowser.py on
  Windows.

DESCRIPTION

  Websourcebrowser starts an internal webserver and listens for HTTP
  requests for directories and files in a project's source code
  directory. The web interface allows to browse the source code with a
  left frame containing the directory tree and a right frame a
  selected file. The directory frame is always accessible.

  If Pygments (http://pygments.org) is installed, files may be
  displayed with syntax highlighting.

  To stop Websourcebrowser, type Ctrl-C (on Posix) or Ctrl-Break (on
  Windows).

WEB INTERFACE

  After invoking Websourcebrowser, it outputs the URL you should put
  in the address line of your webbrowser. After you've done this, you
  get a display with two frames: The left displays the directory
  specified by the --root option (or the default), the right shows a
  placeholder. If you click a link in the left frame denoting a file,
  it's shown in the right frame. If the file is a binary file for
  which Websourcebrowser doesn't know to render it, a hexdump is shown
  instead. At the moment, this happens even for popular formats as
  PDF, and that will change.

  The directory display on the left has several framed links which you
  can imagine as buttons. "Reset view" resets the display, this is as
  if you just entered the root URL which Websourcebrowser prints in
  the terminal upon start. The button "Homepage" opens a new window
  with the page identified with the command line option
  --project-homepage. Below the two already described buttons you can
  control the number of expanded directory levels. By definition, when
  the level is 1, just a linear list of the directories and files in
  the project root directory is shown. A level of 2 means that the
  contained directories and files are also displayed. This is easier
  to check out than to describe. Note that you won't see a difference
  after a click if the project directory structure is not that deep.
  By the way, clicking on a directory link will show a list of its
  contents if they're not already displayed. If, for your taste, too
  many levels are shown, you can reduce them with the buttons at the
  top of the frame.

OPTIONS

  -h, --help
        Show this help text and exit.

  -r ROOT, --root=ROOT
        Set the document root directory (default: current directory).
        For example, if --root=/my/greatproject is specified, the URL
        path / will correspond to the directory /my/greatproject.
        Directories or files "above" the root directory aren't
        accessible (probably, see section BUGS).

  -t PROJECT_TITLE, --project-title=PROJECT_TITLE
        Set the project title to display as the title of the frameset
        (default: capitalized base name of the root directory, so the
        above root option sets a project title "Greatproject").

  --project-homepage=PROJECT_HOMEPAGE
        Make the specified URL accessible via the "Homepage" link in
        the left frame (default: the Websourcebrowser homepage).

  -d DIR_LEVELS, --dir-levels=DIR_LEVELS
        Set the directory nesting level for the tree display in the
        left frame (default: 1). The number 1 denotes a linear list, 2
        additionally shows the direct subdirectories etc.

        Using a large number will display the directory tree
        completely expanded but may make the browsing rather slow for
        a large directory tree. Thus it's recommended to keep the
        default, 1.

  --dir-indent=DIR_INDENT
        Set the number of characters for indentation per directory
        level (default: 4).

  -i PATTERN, --ignore-pattern=PATTERN
        Ignore directories and files matching this pattern (default:
        nothing is ignored). To specify more than one pattern, repeat
        this option.

        Example: To ignore all Subversion bookkeeping files, use
        --ignore-pattern="/*.svn" --ignore-pattern="/*.svn/*"

  -l, --line-numbers
        Prepend lines of text files with line numbers (default: no
        line numbers).

        This works only if Pygments is installed, otherwise this
        option is ignored.

  --http-host=HTTP_HOST
        Use the specified host name or IP for the local interface to
        listen on (default: localhost).

        With the defaults for --http-host and --http-port, the address
        line in the browser is http://localhost:8000/ .

  --http-port=HTTP_PORT
        Listen on this HTTP port (default: 8000).

        With the defaults for --http-host and --http-port, the address
        line in the browser is http://localhost:8000/ .

  -c CLIENT, --allowed-client=CLIENT
        Allow remote access from this host name or IP address
        (default: allow only access from localhost). The localhost
        address is always included. For multiple host names or IP
        addresses use the option several times. For example:

        wsbrowser -c my.host.com -c 199.243.19.27

        As a special case, specifying ALL as the options value accepts
        requests from all addresses and so effectively makes
        Websourcebrowser a web server on the public internet, unless
        prevented by a router or firewall.

  --logging
        Activate logging of HTTP accesses to standard output (default:
        no logging).

ENVIRONMENT

  WSB_IGNORE
        Set wildcard patterns to ignore. If multiple patterns are
        given, they must be separated with whitespace.

        A typical example for WSB_IGNORE might be
        *.pyc  *.pyo  */.svn  *.svn/*  */.hg  */.hg/*  *.swp

        If both this environment variable and one or more
        --ignore-pattern options are used, the patterns from the
        command line are added to those from the environment variable.

BUGS

  Probably there are some bugs as Websourcebrowser is still alpha
  software. Currently, I don't recommend to use Websourcebrowser for
  use on the public internet because it may contain significant
  vulnerabilities. (I indeed paid attention to security though I would
  welcome an experienced fellow to spot security problems.)

  Since the software is still in the alpha stage, it may still change
  significantly. This may include incompatible variations like
  removing command line options or changing their semantics.

AUTHOR

  The author of Websourcebrowser is
  Stefan Schwarzer <sschwarzer@sschwarzer.net>.

SEE ALSO

  The pydoc module in the Python distribution similarly acts as a
  webserver if it's invoked as a program with the option -p and a port
  number.
"""

import optparse
import os
import socket
import sys

# Websourcebrowser modules
import coding
import tools

#
# constants used in several places
#
CSS_FILE_NAME = "websourcebrowser.css"
# window targets
DIR_WINDOW_TARGET = "websourcebrowser_dir"
SOURCE_WINDOW_TARGET = "websourcebrowser_source"
HELP_WINDOW_TARGET = "websourcebrowser_help"
# used to distinguish actual files from directories or files for
#  internal use, e. g. style sheets
SPECIAL_DIR = "_WEBSOURCEBROWSER_"
ALL_CLIENTS = "all_clients_allowed"

#
# defaults, can be changed via command line
#

# project root directory
root = os.getcwd()

# project title, included in HTML `title` and `h1` tags; if `None`,
#  use the basename of the root directory (see above), i. e. if the
#  root directory is "/some/project/path", the title becomes "Path"
project_title = None

# the project's homepage, as linked in the directory navigation pane
project_homepage = "http://websourcebrowser.sschwarzer.net"

# show that many recursive levels of directory items; 1 means to just
#  display the immediate directory contents but nothing below
# Note: the higher this number, the more sluggish the applications
#  become if you have deeply-nested directories with many items
dir_levels = 1

# amount of indentation per directory level in recursive listings;
#  usually a number of "&nbsp;" strings
dir_indent = 4

# list of glob patterns for files/directories to ignore; the patterns
#  account for the directory part, i. e. use ["*/.svn", "*/.svn/*"] to
#  ignore the Subversion metadata directory and all contained items
ignore_patterns = []

# if true, include line numbers in listings
line_numbers = False

# the local HTTP interface
http_host = 'localhost'

# the HTTP port to listen on
http_port = 8000

# clients which are allowed to access this server
allowed_clients = ['localhost']

# if true, log each GET request on stdout
logging = False


def set_from_args(args=None):
    """
    (Re)set the configuration values in the module from the provided
    list of arguments `args`, compatible to what `sys.argv[1:]`
    usually contains. The command line values are the default if
    `args` is not set or `None`.

    >>> import config
    >>> config.set_from_args(["-t", u"Cool project", '--ignore-pattern=*/.svn',
    ...                       '--ignore-pattern=*/.svn/*', '--http-port=8080',
    ...                       '--line-numbers'])
    >>> config.project_title
    u'Cool project'
    >>> config.ignore_patterns
    ['*/.svn', '*/.svn/*']
    >>> config.http_port   # the port value is an integer
    8080
    >>> config.dir_levels  # like the number of directory nesting levels
    1
    >>> config.line_numbers, config.logging
    (True, False)
    """
    if args is None:
        args = sys.argv[1:]
    # set up command line parser
    parser = optparse.OptionParser(add_help_option=False)
    parser.add_option("-h", "--help", action='store_true')
    parser.add_option("-r", "--root", help="document root [current directory]")
    parser.add_option("-t", "--project-title",
                      help="project title to use in HTML title "
                           "[last part of root dir]")
    parser.add_option("--project-homepage",
                      help="homepage URL of the project [Websourcebrowser URL]")
    parser.add_option("-d", "--dir-levels", type='int',
                      help="display directory listings that many levels "
                           "deep [1]")
    parser.add_option("--dir-indent", type='int',
                      help="number of spaces for each indentation "
                           "level in a directory tree [%default]")
    parser.add_option("-i", "--ignore-pattern", metavar="PATTERN",
                      dest='ignore_patterns', action='append',
                      help='ignore dirs/files matching this pattern '
                           '(e. g. "*/.svn/*") [nothing ignored]')
    parser.add_option("-l", "--line-numbers", action='store_true',
                      help="prepend text lines with line numbers [no]")
    parser.add_option("--http-host", help="local HTTP interface [localhost]")
    parser.add_option("--http-port", type='int',
                      help="HTTP port to listen on [%default]")
    parser.add_option("-c", "--allowed-client", metavar="CLIENT",
                      dest='allowed_clients', action='append',
                      help="allow a remote client to connect [localhost]; "
                           "use ALL to run as a public server")
    parser.add_option("--logging", action='store_true',
                      help="log HTTP accesses to stdout [no]")
    parser.set_defaults(**globals())
    (options, args) = parser.parse_args(args)
    if options.help:
        print MAN_PAGE
        sys.exit()
    # from here on, `args` is the list of only the positional arguments!
    if args:
        parser.error("program doesn't take arguments")
    options.root = tools.normalize_path(os.path.expanduser(options.root))
    if options.project_title is None:
        options.project_title = os.path.basename(options.root).capitalize()
    options.project_title = coding.decode(options.project_title)
    # normalize allowed clients to IPs
    allowed_clients = set()
    dummy_port = 80
    global invalid_clients
    invalid_clients = []
    for client in options.allowed_clients:
        if client == "ALL":
            allowed_clients = ALL_CLIENTS
            break
        try:
            for addr_info in socket.getaddrinfo(client, dummy_port):
                allowed_clients.add(addr_info[4][0])
        except socket.gaierror:
            invalid_clients.append(client)
    options.allowed_clients = allowed_clients
    # copy changed configuration back to module namespace; do not use
    #  `globals().update()` because that may copy too much
    option_names = ['root', 'project_title', 'project_homepage', 'dir_levels',
                    'dir_indent', 'ignore_patterns', 'line_numbers',
                    'http_host', 'http_port', 'allowed_clients', 'logging']
    for name in option_names:
        globals()[name] = getattr(options, name)

def set_from_environment():
    """
    Inspect the environment to set some configuration parameters.

    Currently, only the ignore patterns are considered, via the
    environment variable `WSB_IGNORE`. Its value is a whitespace-
    separated string of patterns, for example
    "*.pyc  *.pyo  */.svn  *.svn/*  */.hg  */.hg/*  *.swp".
    """
    global ignore_patterns
    environ = os.environ
    patterns = environ.get('WSB_IGNORE', "")
    for pattern in patterns.split():
        ignore_patterns.append(pattern)