root/urlpath.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.

import os
import urllib

# Websourcebrowser modules
import tools


# separator in URLs
sep = "/"

class NotUnderRoot(Exception):
    pass

def _is_file_system_root(path):
    r"""
    Return `True` if `path` is a file system root directory, else
    `False`.

    Under Posix, the file system root directory is "/", under
    Windows, it's r"x:\", where x is any drive letter.
    """
    path = tools.normalize_path(path)
    drive, rest = os.path.splitdrive(path)
    return rest == os.sep

def is_safe_path(root, path):
    """
    Return `True` if the `path` is a subdirectory of or a file
    under the document root directory `root`, else return `False`.
    """
    root = tools.normalize_path(root)
    path = tools.normalize_path(path)
    if root == path:
        return True
    if _is_file_system_root(root):
        return path.startswith(root)
    else:
        return path.startswith(root + os.sep)

def to_url(root, path):
    r"""
    Return an absolute URL (starting with a slash, without host and
    port part) which is derived from the absolute file system path
    `path`. The argument `root` is the document root (a file system
    path) to take into account.

    Trailing path separators on the `root` or `path` are ignored.

    If the `path` isn't part of the `root`, raise a `NotUnderRoot`
    exception.
    """
    if not is_safe_path(root, path):
        raise NotUnderRoot('path "%s" isn\'t under root directory "%s"' %
                           (path, root))
    root = tools.normalize_path(root)
    path = tools.normalize_path(path)
    # `reduced_path` is not yet an URL but contains the
    #  platform-specific path separator
    reduced_path = path.replace(root, "", 1)
    if root == path:
        return "/"
    if _is_file_system_root(root):
        reduced_path = "/" + reduced_path
    url = reduced_path.replace(os.sep, sep)
    return urllib.quote(url)

def to_file_system(root, url):
    r"""
    Return a file system path (with the proper separator for the used
    platform) derived from `root` and `url`. The `root` argument is
    the document root directory while `url` is an absolute URL (with
    leading slash, without host name).

    Trailing path separators on the `root` or `url` are ignored.

    If the `path` isn't part of the `root`, raise a `NotUnderRoot`
    exception.
    """
    root = tools.normalize_path(root)
    url = urllib.unquote(url)
    reduced_path = url.replace(sep, os.sep)
    path = os.path.join(root, reduced_path[1:])
    path = tools.normalize_path(path)
    if not is_safe_path(root, path):
        raise NotUnderRoot('path "%s" isn\'t under root directory "%s"' %
                           (path, root))
    return path