/brz/remove-bazaar

To get this branch, use:
bzr branch http://gegoxaren.bato24.eu/bzr/brz/remove-bazaar

« back to all changes in this revision

Viewing changes to bzrlib/urlutils.py

  • Committer: Ian Clatworthy
  • Date: 2007-11-14 03:50:56 UTC
  • mto: (3054.1.1 ianc-integration)
  • mto: This revision was merged to the branch mainline in revision 3055.
  • Revision ID: ian.clatworthy@internode.on.net-20071114035056-72l6odzpby4bcmub
First cut at new look User Guide including chapters 1 and 2

Show diffs side-by-side

added added

removed removed

Lines of Context:
1
 
# Copyright (C) 2006-2010 Canonical Ltd
 
1
# Bazaar -- distributed version control
 
2
#
 
3
# Copyright (C) 2006 Canonical Ltd
2
4
#
3
5
# This program is free software; you can redistribute it and/or modify
4
6
# it under the terms of the GNU General Public License as published by
12
14
#
13
15
# You should have received a copy of the GNU General Public License
14
16
# along with this program; if not, write to the Free Software
15
 
# Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA
 
17
# Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
16
18
 
17
19
"""A collection of function for handling URL operations."""
18
20
 
24
26
lazy_import(globals(), """
25
27
from posixpath import split as _posix_split, normpath as _posix_normpath
26
28
import urllib
27
 
import urlparse
28
29
 
29
30
from bzrlib import (
30
31
    errors,
66
67
        relpath = relpath.encode('utf-8')
67
68
    # After quoting and encoding, the path should be perfectly
68
69
    # safe as a plain ASCII string, str() just enforces this
69
 
    return str(urllib.quote(relpath, safe='/~'))
 
70
    return str(urllib.quote(relpath))
70
71
 
71
72
 
72
73
def file_relpath(base, path):
73
74
    """Compute just the relative sub-portion of a url
74
 
 
 
75
    
75
76
    This assumes that both paths are already fully specified file:// URLs.
76
77
    """
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))
 
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
 
81
82
    base = local_path_from_url(base)
82
83
    path = local_path_from_url(path)
83
84
    return escape(osutils.relpath(base, path))
183
184
 
184
185
def joinpath(base, *args):
185
186
    """Join URL path segments to a URL path segment.
186
 
 
 
187
    
187
188
    This is somewhat like osutils.joinpath, but intended for URLs.
188
189
 
189
190
    XXX: this duplicates some normalisation logic, and also duplicates a lot of
217
218
# jam 20060502 Sorted to 'l' because the final target is 'local_path_from_url'
218
219
def _posix_local_path_from_url(url):
219
220
    """Convert a url like file:///path/to/foo into /path/to/foo"""
220
 
    file_localhost_prefix = 'file://localhost/'
221
 
    if url.startswith(file_localhost_prefix):
222
 
        path = url[len(file_localhost_prefix) - 1:]
223
 
    elif not url.startswith('file:///'):
224
 
        raise errors.InvalidURL(
225
 
            url, 'local urls must start with file:/// or file://localhost/')
226
 
    else:
227
 
        path = url[len('file://'):]
 
221
    if not url.startswith('file:///'):
 
222
        raise errors.InvalidURL(url, 'local urls must start with file:///')
228
223
    # We only strip off 2 slashes
229
 
    return unescape(path)
 
224
    return unescape(url[len('file://'):])
230
225
 
231
226
 
232
227
def _posix_local_path_to_url(path):
234
229
 
235
230
    This also handles transforming escaping unicode characters, etc.
236
231
    """
237
 
    # importing directly from posixpath allows us to test this
 
232
    # importing directly from posixpath allows us to test this 
238
233
    # on non-posix platforms
239
234
    return 'file://' + escape(_posix_normpath(
240
235
        osutils._posix_abspath(path)))
254
249
            raise errors.InvalidURL(url, 'Win32 UNC path urls'
255
250
                ' have form file://HOST/path')
256
251
        return unescape(win32_url)
257
 
 
258
 
    # allow empty paths so we can serve all roots
259
 
    if win32_url == '///':
260
 
        return '/'
261
 
 
262
252
    # usual local path with drive letter
263
253
    if (win32_url[3] not in ('abcdefghijklmnopqrstuvwxyz'
264
254
                             'ABCDEFGHIJKLMNOPQRSTUVWXYZ')
274
264
 
275
265
    This also handles transforming escaping unicode characters, etc.
276
266
    """
277
 
    # importing directly from ntpath allows us to test this
 
267
    # importing directly from ntpath allows us to test this 
278
268
    # on non-win32 platform
279
269
    # FIXME: It turns out that on nt, ntpath.abspath uses nt._getfullpathname
280
270
    #       which actually strips trailing space characters.
281
 
    #       The worst part is that on linux ntpath.abspath has different
 
271
    #       The worst part is that under linux ntpath.abspath has different
282
272
    #       semantics, since 'nt' is not an available module.
283
 
    if path == '/':
284
 
        return 'file:///'
285
 
 
286
273
    win32_path = osutils._win32_abspath(path)
287
274
    # check for UNC path \\HOST\path
288
275
    if win32_path.startswith('//'):
289
276
        return 'file:' + escape(win32_path)
290
 
    return ('file:///' + str(win32_path[0].upper()) + ':' +
291
 
        escape(win32_path[2:]))
 
277
    return 'file:///' + win32_path[0].upper() + ':' + escape(win32_path[2:])
292
278
 
293
279
 
294
280
local_path_to_url = _posix_local_path_to_url
309
295
 
310
296
def _unescape_safe_chars(matchobj):
311
297
    """re.sub callback to convert hex-escapes to plain characters (if safe).
312
 
 
 
298
    
313
299
    e.g. '%7E' will be converted to '~'.
314
300
    """
315
301
    hex_digits = matchobj.group(0)[1:]
322
308
 
323
309
def normalize_url(url):
324
310
    """Make sure that a path string is in fully normalized URL form.
325
 
 
 
311
    
326
312
    This handles URLs which have unicode characters, spaces,
327
313
    special characters, etc.
328
314
 
374
360
    dummy, base_first_slash = _find_scheme_and_separator(base)
375
361
    if base_first_slash is None:
376
362
        return other
377
 
 
 
363
    
378
364
    dummy, other_first_slash = _find_scheme_and_separator(other)
379
365
    if other_first_slash is None:
380
366
        return other
384
370
    other_scheme = other[:other_first_slash]
385
371
    if base_scheme != other_scheme:
386
372
        return other
387
 
    elif sys.platform == 'win32' and base_scheme == 'file://':
388
 
        base_drive = base[base_first_slash+1:base_first_slash+3]
389
 
        other_drive = other[other_first_slash+1:other_first_slash+3]
390
 
        if base_drive != other_drive:
391
 
            return other
392
373
 
393
374
    base_path = base[base_first_slash+1:]
394
375
    other_path = other[other_first_slash+1:]
422
403
    # Strip off the drive letter
423
404
    # path is currently /C:/foo
424
405
    if len(path) < 3 or path[2] not in ':|' or path[3] != '/':
425
 
        raise errors.InvalidURL(url_base + path,
 
406
        raise errors.InvalidURL(url_base + path, 
426
407
            'win32 file:/// paths need a drive letter')
427
408
    url_base += path[0:3] # file:// + /C:
428
409
    path = path[3:] # /foo
436
417
    :param exclude_trailing_slash: Strip off a final '/' if it is part
437
418
        of the path (but not if it is part of the protocol specification)
438
419
 
439
 
    :return: (parent_url, child_dir).  child_dir may be the empty string if we're at
 
420
    :return: (parent_url, child_dir).  child_dir may be the empty string if we're at 
440
421
        the root.
441
422
    """
442
423
    scheme_loc, first_path_slash = _find_scheme_and_separator(url)
469
450
    return url_base + head, tail
470
451
 
471
452
 
472
 
def split_segment_parameters_raw(url):
473
 
    """Split the subsegment of the last segment of a URL.
474
 
 
475
 
    :param url: A relative or absolute URL
476
 
    :return: (url, subsegments)
477
 
    """
478
 
    (parent_url, child_dir) = split(url)
479
 
    subsegments = child_dir.split(",")
480
 
    if len(subsegments) == 1:
481
 
        return (url, [])
482
 
    return (join(parent_url, subsegments[0]), subsegments[1:])
483
 
 
484
 
 
485
 
def split_segment_parameters(url):
486
 
    """Split the segment parameters of the last segment of a URL.
487
 
 
488
 
    :param url: A relative or absolute URL
489
 
    :return: (url, segment_parameters)
490
 
    """
491
 
    (base_url, subsegments) = split_segment_parameters_raw(url)
492
 
    parameters = {}
493
 
    for subsegment in subsegments:
494
 
        (key, value) = subsegment.split("=", 1)
495
 
        parameters[key] = value
496
 
    return (base_url, parameters)
497
 
 
498
 
 
499
 
def join_segment_parameters_raw(base, *subsegments):
500
 
    """Create a new URL by adding subsegments to an existing one. 
501
 
 
502
 
    This adds the specified subsegments to the last path in the specified
503
 
    base URL. The subsegments should be bytestrings.
504
 
 
505
 
    :note: You probably want to use join_segment_parameters instead.
506
 
    """
507
 
    if not subsegments:
508
 
        return base
509
 
    for subsegment in subsegments:
510
 
        if type(subsegment) is not str:
511
 
            raise TypeError("Subsegment %r is not a bytestring" % subsegment)
512
 
        if "," in subsegment:
513
 
            raise errors.InvalidURLJoin(", exists in subsegments",
514
 
                                        base, subsegments)
515
 
    return ",".join((base,) + subsegments)
516
 
 
517
 
 
518
 
def join_segment_parameters(url, parameters):
519
 
    """Create a new URL by adding segment parameters to an existing one.
520
 
 
521
 
    The parameters of the last segment in the URL will be updated; if a
522
 
    parameter with the same key already exists it will be overwritten.
523
 
 
524
 
    :param url: A URL, as string
525
 
    :param parameters: Dictionary of parameters, keys and values as bytestrings
526
 
    """
527
 
    (base, existing_parameters) = split_segment_parameters(url)
528
 
    new_parameters = {}
529
 
    new_parameters.update(existing_parameters)
530
 
    for key, value in parameters.iteritems():
531
 
        if type(key) is not str:
532
 
            raise TypeError("parameter key %r is not a bytestring" % key)
533
 
        if type(value) is not str:
534
 
            raise TypeError("parameter value %r for %s is not a bytestring" %
535
 
                (key, value))
536
 
        if "=" in key:
537
 
            raise errors.InvalidURLJoin("= exists in parameter key", url,
538
 
                parameters)
539
 
        new_parameters[key] = value
540
 
    return join_segment_parameters_raw(base, 
541
 
        *["%s=%s" % item for item in sorted(new_parameters.items())])
542
 
 
543
 
 
544
453
def _win32_strip_local_trailing_slash(url):
545
454
    """Strip slashes after the drive letter"""
546
455
    if len(url) > WIN32_MIN_ABS_FILEURL_LENGTH:
618
527
# These are characters that if escaped, should stay that way
619
528
_no_decode_chars = ';/?:@&=+$,#'
620
529
_no_decode_ords = [ord(c) for c in _no_decode_chars]
621
 
_no_decode_hex = (['%02x' % o for o in _no_decode_ords]
 
530
_no_decode_hex = (['%02x' % o for o in _no_decode_ords] 
622
531
                + ['%02X' % o for o in _no_decode_ords])
623
532
_hex_display_map = dict(([('%02x' % o, chr(o)) for o in range(256)]
624
533
                    + [('%02X' % o, chr(o)) for o in range(256)]))
650
559
    This will turn file:// urls into local paths, and try to decode
651
560
    any portions of a http:// style url that it can.
652
561
 
653
 
    Any sections of the URL which can't be represented in the encoding or
 
562
    Any sections of the URL which can't be represented in the encoding or 
654
563
    need to stay as escapes are left alone.
655
564
 
656
565
    :param url: A 7-bit ASCII URL
657
566
    :param encoding: The final output encoding
658
567
 
659
 
    :return: A unicode string which can be safely encoded into the
 
568
    :return: A unicode string which can be safely encoded into the 
660
569
         specified encoding.
661
570
    """
662
 
    if encoding is None:
663
 
        raise ValueError('you cannot specify None for the display encoding')
 
571
    assert encoding is not None, 'you cannot specify None for the display encoding.'
664
572
    if url.startswith('file://'):
665
573
        try:
666
574
            path = local_path_from_url(url)
721
629
            return from_location[sep+1:]
722
630
        else:
723
631
            return from_location
724
 
 
725
 
 
726
 
def _is_absolute(url):
727
 
    return (osutils.pathjoin('/foo', url) == url)
728
 
 
729
 
 
730
 
def rebase_url(url, old_base, new_base):
731
 
    """Convert a relative path from an old base URL to a new base URL.
732
 
 
733
 
    The result will be a relative path.
734
 
    Absolute paths and full URLs are returned unaltered.
735
 
    """
736
 
    scheme, separator = _find_scheme_and_separator(url)
737
 
    if scheme is not None:
738
 
        return url
739
 
    if _is_absolute(url):
740
 
        return url
741
 
    old_parsed = urlparse.urlparse(old_base)
742
 
    new_parsed = urlparse.urlparse(new_base)
743
 
    if (old_parsed[:2]) != (new_parsed[:2]):
744
 
        raise errors.InvalidRebaseURLs(old_base, new_base)
745
 
    return determine_relative_path(new_parsed[2],
746
 
                                   join(old_parsed[2], url))
747
 
 
748
 
 
749
 
def determine_relative_path(from_path, to_path):
750
 
    """Determine a relative path from from_path to to_path."""
751
 
    from_segments = osutils.splitpath(from_path)
752
 
    to_segments = osutils.splitpath(to_path)
753
 
    count = -1
754
 
    for count, (from_element, to_element) in enumerate(zip(from_segments,
755
 
                                                       to_segments)):
756
 
        if from_element != to_element:
757
 
            break
758
 
    else:
759
 
        count += 1
760
 
    unique_from = from_segments[count:]
761
 
    unique_to = to_segments[count:]
762
 
    segments = (['..'] * len(unique_from) + unique_to)
763
 
    if len(segments) == 0:
764
 
        return '.'
765
 
    return osutils.pathjoin(*segments)
766
 
 
767
 
 
768
 
 
769
 
def parse_url(url):
770
 
    """Extract the server address, the credentials and the path from the url.
771
 
 
772
 
    user, password, host and path should be quoted if they contain reserved
773
 
    chars.
774
 
 
775
 
    :param url: an quoted url
776
 
 
777
 
    :return: (scheme, user, password, host, port, path) tuple, all fields
778
 
        are unquoted.
779
 
    """
780
 
    if isinstance(url, unicode):
781
 
        raise errors.InvalidURL('should be ascii:\n%r' % url)
782
 
    url = url.encode('utf-8')
783
 
    (scheme, netloc, path, params,
784
 
     query, fragment) = urlparse.urlparse(url, allow_fragments=False)
785
 
    user = password = host = port = None
786
 
    if '@' in netloc:
787
 
        user, host = netloc.rsplit('@', 1)
788
 
        if ':' in user:
789
 
            user, password = user.split(':', 1)
790
 
            password = urllib.unquote(password)
791
 
        user = urllib.unquote(user)
792
 
    else:
793
 
        host = netloc
794
 
 
795
 
    if ':' in host and not (host[0] == '[' and host[-1] == ']'): #there *is* port
796
 
        host, port = host.rsplit(':',1)
797
 
        try:
798
 
            port = int(port)
799
 
        except ValueError:
800
 
            raise errors.InvalidURL('invalid port number %s in url:\n%s' %
801
 
                                    (port, url))
802
 
    if host != "" and host[0] == '[' and host[-1] == ']': #IPv6
803
 
        host = host[1:-1]
804
 
 
805
 
    host = urllib.unquote(host)
806
 
    path = urllib.unquote(path)
807
 
 
808
 
    return (scheme, user, password, host, port, path)