← Back to branch summary

~bzr-pqm/bzr/bzr.dev

« back to all changes in this revision

Viewing changes to bzrlib/urlutils.py

  • Committer: Canonical.com Patch Queue Manager
  • Date: 2010-11-06 16:01:48 UTC
  • mfrom: (5527.1.1 trunk)
  • Revision ID: pqm@pqm.ubuntu.com-20101106160148-8maemz21jbrhpzky
(vila) Move NEWS entry into the correct section (Vincent Ladeuil)

Show diffs side-by-side

added added

removed removed

Lines of Context:
bzrlib/urlutils.py
1
 
# Bazaar -- distributed version control
2
 
#
3
 
# Copyright (C) 2006 Canonical Ltd
 
1
# Copyright (C) 2006-2010 Canonical Ltd
4
2
#
5
3
# This program is free software; you can redistribute it and/or modify
6
4
# it under the terms of the GNU General Public License as published by
14
12
#
15
13
# You should have received a copy of the GNU General Public License
16
14
# along with this program; if not, write to the Free Software
17
 
# Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
 
15
# Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA
18
16
 
19
17
"""A collection of function for handling URL operations."""
20
18
 
26
24
lazy_import(globals(), """
27
25
from posixpath import split as _posix_split, normpath as _posix_normpath
28
26
import urllib
 
27
import urlparse
29
28
 
30
29
from bzrlib import (
31
30
    errors,
67
66
        relpath = relpath.encode('utf-8')
68
67
    # After quoting and encoding, the path should be perfectly
69
68
    # safe as a plain ASCII string, str() just enforces this
70
 
    return str(urllib.quote(relpath))
 
69
    return str(urllib.quote(relpath, safe='/~'))
71
70
 
72
71
 
73
72
def file_relpath(base, path):
74
73
    """Compute just the relative sub-portion of a url
75
 
    
 
74
 
76
75
    This assumes that both paths are already fully specified file:// URLs.
77
76
    """
78
 
    assert len(base) >= MIN_ABS_FILEURL_LENGTH, ('Length of base must be equal or'
79
 
        ' exceed the platform minimum url length (which is %d)' % 
80
 
        MIN_ABS_FILEURL_LENGTH)
81
 
 
 
77
    if len(base) < MIN_ABS_FILEURL_LENGTH:
 
78
        raise ValueError('Length of base (%r) must equal or'
 
79
            ' exceed the platform minimum url length (which is %d)' %
 
80
            (base, MIN_ABS_FILEURL_LENGTH))
82
81
    base = local_path_from_url(base)
83
82
    path = local_path_from_url(path)
84
83
    return escape(osutils.relpath(base, path))
102
101
    first_path_slash = path.find('/')
103
102
    if first_path_slash == -1:
104
103
        return len(scheme), None
105
 
    return len(scheme), first_path_slash+len(scheme)+3
 
104
    return len(scheme), first_path_slash+m.start('path')
 
105
 
 
106
 
 
107
def is_url(url):
 
108
    """Tests whether a URL is in actual fact a URL."""
 
109
    return _url_scheme_re.match(url) is not None
106
110
 
107
111
 
108
112
def join(base, *args):
119
123
    """
120
124
    if not args:
121
125
        return base
122
 
    match = _url_scheme_re.match(base)
123
 
    scheme = None
124
 
    if match:
125
 
        scheme = match.group('scheme')
126
 
        path = match.group('path').split('/')
127
 
        if path[-1:] == ['']:
128
 
            # Strip off a trailing slash
129
 
            # This helps both when we are at the root, and when
130
 
            # 'base' has an extra slash at the end
131
 
            path = path[:-1]
132
 
    else:
133
 
        path = base.split('/')
134
 
 
135
 
    if scheme is not None and len(path) >= 1:
136
 
        host = path[:1]
137
 
        # the path should be represented as an abs path.
138
 
        # we know this must be absolute because of the presence of a URL scheme.
139
 
        remove_root = True
140
 
        path = [''] + path[1:]
141
 
    else:
142
 
        # create an empty host, but dont alter the path - this might be a
143
 
        # relative url fragment.
144
 
        host = []
145
 
        remove_root = False
146
 
 
 
126
    scheme_end, path_start = _find_scheme_and_separator(base)
 
127
    if scheme_end is None and path_start is None:
 
128
        path_start = 0
 
129
    elif path_start is None:
 
130
        path_start = len(base)
 
131
    path = base[path_start:]
147
132
    for arg in args:
148
 
        match = _url_scheme_re.match(arg)
149
 
        if match:
150
 
            # Absolute URL
151
 
            scheme = match.group('scheme')
152
 
            # this skips .. normalisation, making http://host/../../..
153
 
            # be rather strange.
154
 
            path = match.group('path').split('/')
155
 
            # set the host and path according to new absolute URL, discarding
156
 
            # any previous values.
157
 
            # XXX: duplicates mess from earlier in this function.  This URL
158
 
            # manipulation code needs some cleaning up.
159
 
            if scheme is not None and len(path) >= 1:
160
 
                host = path[:1]
161
 
                path = path[1:]
162
 
                # url scheme implies absolute path.
163
 
                path = [''] + path
164
 
            else:
165
 
                # no url scheme we take the path as is.
166
 
                host = []
 
133
        arg_scheme_end, arg_path_start = _find_scheme_and_separator(arg)
 
134
        if arg_scheme_end is None and arg_path_start is None:
 
135
            arg_path_start = 0
 
136
        elif arg_path_start is None:
 
137
            arg_path_start = len(arg)
 
138
        if arg_scheme_end is not None:
 
139
            base = arg
 
140
            path = arg[arg_path_start:]
 
141
            scheme_end = arg_scheme_end
 
142
            path_start = arg_path_start
167
143
        else:
168
 
            path = '/'.join(path)
169
144
            path = joinpath(path, arg)
170
 
            path = path.split('/')
171
 
    if remove_root and path[0:1] == ['']:
172
 
        del path[0]
173
 
    if host:
174
 
        # Remove the leading slash from the path, so long as it isn't also the
175
 
        # trailing slash, which we want to keep if present.
176
 
        if path and path[0] == '' and len(path) > 1:
177
 
            del path[0]
178
 
        path = host + path
179
 
 
180
 
    if scheme is None:
181
 
        return '/'.join(path)
182
 
    return scheme + '://' + '/'.join(path)
 
145
    return base[:path_start] + path
183
146
 
184
147
 
185
148
def joinpath(base, *args):
186
149
    """Join URL path segments to a URL path segment.
187
 
    
 
150
 
188
151
    This is somewhat like osutils.joinpath, but intended for URLs.
189
152
 
190
153
    XXX: this duplicates some normalisation logic, and also duplicates a lot of
218
181
# jam 20060502 Sorted to 'l' because the final target is 'local_path_from_url'
219
182
def _posix_local_path_from_url(url):
220
183
    """Convert a url like file:///path/to/foo into /path/to/foo"""
221
 
    if not url.startswith('file:///'):
222
 
        raise errors.InvalidURL(url, 'local urls must start with file:///')
 
184
    file_localhost_prefix = 'file://localhost/'
 
185
    if url.startswith(file_localhost_prefix):
 
186
        path = url[len(file_localhost_prefix) - 1:]
 
187
    elif not url.startswith('file:///'):
 
188
        raise errors.InvalidURL(
 
189
            url, 'local urls must start with file:/// or file://localhost/')
 
190
    else:
 
191
        path = url[len('file://'):]
223
192
    # We only strip off 2 slashes
224
 
    return unescape(url[len('file://'):])
 
193
    return unescape(path)
225
194
 
226
195
 
227
196
def _posix_local_path_to_url(path):
229
198
 
230
199
    This also handles transforming escaping unicode characters, etc.
231
200
    """
232
 
    # importing directly from posixpath allows us to test this 
 
201
    # importing directly from posixpath allows us to test this
233
202
    # on non-posix platforms
234
203
    return 'file://' + escape(_posix_normpath(
235
204
        osutils._posix_abspath(path)))
249
218
            raise errors.InvalidURL(url, 'Win32 UNC path urls'
250
219
                ' have form file://HOST/path')
251
220
        return unescape(win32_url)
 
221
 
 
222
    # allow empty paths so we can serve all roots
 
223
    if win32_url == '///':
 
224
        return '/'
 
225
 
252
226
    # usual local path with drive letter
253
 
    if (win32_url[3] not in ('abcdefghijklmnopqrstuvwxyz'
254
 
                             'ABCDEFGHIJKLMNOPQRSTUVWXYZ')
 
227
    if (len(win32_url) < 6
 
228
        or win32_url[3] not in ('abcdefghijklmnopqrstuvwxyz'
 
229
                                'ABCDEFGHIJKLMNOPQRSTUVWXYZ')
255
230
        or win32_url[4] not in  '|:'
256
231
        or win32_url[5] != '/'):
257
232
        raise errors.InvalidURL(url, 'Win32 file urls start with'
264
239
 
265
240
    This also handles transforming escaping unicode characters, etc.
266
241
    """
267
 
    # importing directly from ntpath allows us to test this 
 
242
    # importing directly from ntpath allows us to test this
268
243
    # on non-win32 platform
269
244
    # FIXME: It turns out that on nt, ntpath.abspath uses nt._getfullpathname
270
245
    #       which actually strips trailing space characters.
271
 
    #       The worst part is that under linux ntpath.abspath has different
 
246
    #       The worst part is that on linux ntpath.abspath has different
272
247
    #       semantics, since 'nt' is not an available module.
 
248
    if path == '/':
 
249
        return 'file:///'
 
250
 
273
251
    win32_path = osutils._win32_abspath(path)
274
252
    # check for UNC path \\HOST\path
275
253
    if win32_path.startswith('//'):
276
254
        return 'file:' + escape(win32_path)
277
 
    return 'file:///' + win32_path[0].upper() + ':' + escape(win32_path[2:])
 
255
    return ('file:///' + str(win32_path[0].upper()) + ':' +
 
256
        escape(win32_path[2:]))
278
257
 
279
258
 
280
259
local_path_to_url = _posix_local_path_to_url
289
268
    MIN_ABS_FILEURL_LENGTH = WIN32_MIN_ABS_FILEURL_LENGTH
290
269
 
291
270
 
292
 
_url_scheme_re = re.compile(r'^(?P<scheme>[^:/]{2,})://(?P<path>.*)$')
 
271
_url_scheme_re = re.compile(r'^(?P<scheme>[^:/]{2,}):(//)?(?P<path>.*)$')
293
272
_url_hex_escapes_re = re.compile(r'(%[0-9a-fA-F]{2})')
294
273
 
295
274
 
296
275
def _unescape_safe_chars(matchobj):
297
276
    """re.sub callback to convert hex-escapes to plain characters (if safe).
298
 
    
 
277
 
299
278
    e.g. '%7E' will be converted to '~'.
300
279
    """
301
280
    hex_digits = matchobj.group(0)[1:]
308
287
 
309
288
def normalize_url(url):
310
289
    """Make sure that a path string is in fully normalized URL form.
311
 
    
 
290
 
312
291
    This handles URLs which have unicode characters, spaces,
313
292
    special characters, etc.
314
293
 
325
304
    :param url: Either a hybrid URL or a local path
326
305
    :return: A normalized URL which only includes 7-bit ASCII characters.
327
306
    """
328
 
    m = _url_scheme_re.match(url)
329
 
    if not m:
 
307
    scheme_end, path_start = _find_scheme_and_separator(url)
 
308
    if scheme_end is None:
330
309
        return local_path_to_url(url)
331
 
    scheme = m.group('scheme')
332
 
    path = m.group('path')
 
310
    prefix = url[:path_start]
 
311
    path = url[path_start:]
333
312
    if not isinstance(url, unicode):
334
313
        for c in url:
335
314
            if c not in _url_safe_characters:
336
315
                raise errors.InvalidURL(url, 'URLs can only contain specific'
337
316
                                            ' safe characters (not %r)' % c)
338
317
        path = _url_hex_escapes_re.sub(_unescape_safe_chars, path)
339
 
        return str(scheme + '://' + ''.join(path))
 
318
        return str(prefix + ''.join(path))
340
319
 
341
320
    # We have a unicode (hybrid) url
342
321
    path_chars = list(path)
348
327
                ['%%%02X' % ord(c) for c in path_chars[i].encode('utf-8')])
349
328
    path = ''.join(path_chars)
350
329
    path = _url_hex_escapes_re.sub(_unescape_safe_chars, path)
351
 
    return str(scheme + '://' + path)
 
330
    return str(prefix + path)
352
331
 
353
332
 
354
333
def relative_url(base, other):
360
339
    dummy, base_first_slash = _find_scheme_and_separator(base)
361
340
    if base_first_slash is None:
362
341
        return other
363
 
    
 
342
 
364
343
    dummy, other_first_slash = _find_scheme_and_separator(other)
365
344
    if other_first_slash is None:
366
345
        return other
408
387
    # Strip off the drive letter
409
388
    # path is currently /C:/foo
410
389
    if len(path) < 3 or path[2] not in ':|' or path[3] != '/':
411
 
        raise errors.InvalidURL(url_base + path, 
 
390
        raise errors.InvalidURL(url_base + path,
412
391
            'win32 file:/// paths need a drive letter')
413
392
    url_base += path[0:3] # file:// + /C:
414
393
    path = path[3:] # /foo
422
401
    :param exclude_trailing_slash: Strip off a final '/' if it is part
423
402
        of the path (but not if it is part of the protocol specification)
424
403
 
425
 
    :return: (parent_url, child_dir).  child_dir may be the empty string if we're at 
 
404
    :return: (parent_url, child_dir).  child_dir may be the empty string if we're at
426
405
        the root.
427
406
    """
428
407
    scheme_loc, first_path_slash = _find_scheme_and_separator(url)
455
434
    return url_base + head, tail
456
435
 
457
436
 
 
437
def split_segment_parameters_raw(url):
 
438
    """Split the subsegment of the last segment of a URL.
 
439
 
 
440
    :param url: A relative or absolute URL
 
441
    :return: (url, subsegments)
 
442
    """
 
443
    (parent_url, child_dir) = split(url)
 
444
    subsegments = child_dir.split(",")
 
445
    if len(subsegments) == 1:
 
446
        return (url, [])
 
447
    return (join(parent_url, subsegments[0]), subsegments[1:])
 
448
 
 
449
 
 
450
def split_segment_parameters(url):
 
451
    """Split the segment parameters of the last segment of a URL.
 
452
 
 
453
    :param url: A relative or absolute URL
 
454
    :return: (url, segment_parameters)
 
455
    """
 
456
    (base_url, subsegments) = split_segment_parameters_raw(url)
 
457
    parameters = {}
 
458
    for subsegment in subsegments:
 
459
        (key, value) = subsegment.split("=", 1)
 
460
        parameters[key] = value
 
461
    return (base_url, parameters)
 
462
 
 
463
 
 
464
def join_segment_parameters_raw(base, *subsegments):
 
465
    """Create a new URL by adding subsegments to an existing one. 
 
466
 
 
467
    This adds the specified subsegments to the last path in the specified
 
468
    base URL. The subsegments should be bytestrings.
 
469
 
 
470
    :note: You probably want to use join_segment_parameters instead.
 
471
    """
 
472
    if not subsegments:
 
473
        return base
 
474
    for subsegment in subsegments:
 
475
        if type(subsegment) is not str:
 
476
            raise TypeError("Subsegment %r is not a bytestring" % subsegment)
 
477
        if "," in subsegment:
 
478
            raise errors.InvalidURLJoin(", exists in subsegments",
 
479
                                        base, subsegments)
 
480
    return ",".join((base,) + subsegments)
 
481
 
 
482
 
 
483
def join_segment_parameters(url, parameters):
 
484
    """Create a new URL by adding segment parameters to an existing one.
 
485
 
 
486
    The parameters of the last segment in the URL will be updated; if a
 
487
    parameter with the same key already exists it will be overwritten.
 
488
 
 
489
    :param url: A URL, as string
 
490
    :param parameters: Dictionary of parameters, keys and values as bytestrings
 
491
    """
 
492
    (base, existing_parameters) = split_segment_parameters(url)
 
493
    new_parameters = {}
 
494
    new_parameters.update(existing_parameters)
 
495
    for key, value in parameters.iteritems():
 
496
        if type(key) is not str:
 
497
            raise TypeError("parameter key %r is not a bytestring" % key)
 
498
        if type(value) is not str:
 
499
            raise TypeError("parameter value %r for %s is not a bytestring" %
 
500
                (key, value))
 
501
        if "=" in key:
 
502
            raise errors.InvalidURLJoin("= exists in parameter key", url,
 
503
                parameters)
 
504
        new_parameters[key] = value
 
505
    return join_segment_parameters_raw(base, 
 
506
        *["%s=%s" % item for item in sorted(new_parameters.items())])
 
507
 
 
508
 
458
509
def _win32_strip_local_trailing_slash(url):
459
510
    """Strip slashes after the drive letter"""
460
511
    if len(url) > WIN32_MIN_ABS_FILEURL_LENGTH:
532
583
# These are characters that if escaped, should stay that way
533
584
_no_decode_chars = ';/?:@&=+$,#'
534
585
_no_decode_ords = [ord(c) for c in _no_decode_chars]
535
 
_no_decode_hex = (['%02x' % o for o in _no_decode_ords] 
 
586
_no_decode_hex = (['%02x' % o for o in _no_decode_ords]
536
587
                + ['%02X' % o for o in _no_decode_ords])
537
588
_hex_display_map = dict(([('%02x' % o, chr(o)) for o in range(256)]
538
589
                    + [('%02X' % o, chr(o)) for o in range(256)]))
564
615
    This will turn file:// urls into local paths, and try to decode
565
616
    any portions of a http:// style url that it can.
566
617
 
567
 
    Any sections of the URL which can't be represented in the encoding or 
 
618
    Any sections of the URL which can't be represented in the encoding or
568
619
    need to stay as escapes are left alone.
569
620
 
570
621
    :param url: A 7-bit ASCII URL
571
622
    :param encoding: The final output encoding
572
623
 
573
 
    :return: A unicode string which can be safely encoded into the 
 
624
    :return: A unicode string which can be safely encoded into the
574
625
         specified encoding.
575
626
    """
576
 
    assert encoding is not None, 'you cannot specify None for the display encoding.'
 
627
    if encoding is None:
 
628
        raise ValueError('you cannot specify None for the display encoding')
577
629
    if url.startswith('file://'):
578
630
        try:
579
631
            path = local_path_from_url(url)
634
686
            return from_location[sep+1:]
635
687
        else:
636
688
            return from_location
 
689
 
 
690
 
 
691
def _is_absolute(url):
 
692
    return (osutils.pathjoin('/foo', url) == url)
 
693
 
 
694
 
 
695
def rebase_url(url, old_base, new_base):
 
696
    """Convert a relative path from an old base URL to a new base URL.
 
697
 
 
698
    The result will be a relative path.
 
699
    Absolute paths and full URLs are returned unaltered.
 
700
    """
 
701
    scheme, separator = _find_scheme_and_separator(url)
 
702
    if scheme is not None:
 
703
        return url
 
704
    if _is_absolute(url):
 
705
        return url
 
706
    old_parsed = urlparse.urlparse(old_base)
 
707
    new_parsed = urlparse.urlparse(new_base)
 
708
    if (old_parsed[:2]) != (new_parsed[:2]):
 
709
        raise errors.InvalidRebaseURLs(old_base, new_base)
 
710
    return determine_relative_path(new_parsed[2],
 
711
                                   join(old_parsed[2], url))
 
712
 
 
713
 
 
714
def determine_relative_path(from_path, to_path):
 
715
    """Determine a relative path from from_path to to_path."""
 
716
    from_segments = osutils.splitpath(from_path)
 
717
    to_segments = osutils.splitpath(to_path)
 
718
    count = -1
 
719
    for count, (from_element, to_element) in enumerate(zip(from_segments,
 
720
                                                       to_segments)):
 
721
        if from_element != to_element:
 
722
            break
 
723
    else:
 
724
        count += 1
 
725
    unique_from = from_segments[count:]
 
726
    unique_to = to_segments[count:]
 
727
    segments = (['..'] * len(unique_from) + unique_to)
 
728
    if len(segments) == 0:
 
729
        return '.'
 
730
    return osutils.pathjoin(*segments)
 
731
 
 
732
 
 
733
 
 
734
def parse_url(url):
 
735
    """Extract the server address, the credentials and the path from the url.
 
736
 
 
737
    user, password, host and path should be quoted if they contain reserved
 
738
    chars.
 
739
 
 
740
    :param url: an quoted url
 
741
 
 
742
    :return: (scheme, user, password, host, port, path) tuple, all fields
 
743
        are unquoted.
 
744
    """
 
745
    if isinstance(url, unicode):
 
746
        raise errors.InvalidURL('should be ascii:\n%r' % url)
 
747
    url = url.encode('utf-8')
 
748
    (scheme, netloc, path, params,
 
749
     query, fragment) = urlparse.urlparse(url, allow_fragments=False)
 
750
    user = password = host = port = None
 
751
    if '@' in netloc:
 
752
        user, host = netloc.rsplit('@', 1)
 
753
        if ':' in user:
 
754
            user, password = user.split(':', 1)
 
755
            password = urllib.unquote(password)
 
756
        user = urllib.unquote(user)
 
757
    else:
 
758
        host = netloc
 
759
 
 
760
    if ':' in host and not (host[0] == '[' and host[-1] == ']'): #there *is* port
 
761
        host, port = host.rsplit(':',1)
 
762
        try:
 
763
            port = int(port)
 
764
        except ValueError:
 
765
            raise errors.InvalidURL('invalid port number %s in url:\n%s' %
 
766
                                    (port, url))
 
767
    if host != "" and host[0] == '[' and host[-1] == ']': #IPv6
 
768
        host = host[1:-1]
 
769
 
 
770
    host = urllib.unquote(host)
 
771
    path = urllib.unquote(path)
 
772
 
 
773
    return (scheme, user, password, host, port, path)