zeroinstall/injector/model.py

   1 """In-memory representation of interfaces and other data structures.
   2
   3 The objects in this module are used to build a representation of an XML interface
   4 file in memory.
   5
   6 @see: L{reader} constructs these data-structures
   7 @see: U{http://0install.net/interface-spec.html} description of the domain model
   8
   9 @var defaults: Default values for the 'default' attribute for <environment> bindings of
  10 well-known variables.
  11 """
  12
  13 # Copyright (C) 2009, Thomas Leonard
  14 # See the README file for details, or visit http://0install.net.
  15
  16 from zeroinstall import _
  17 import os, re, locale
  18 from logging import info, debug, warn
  19 from zeroinstall import SafeException, version
  20 from zeroinstall.injector.namespaces import XMLNS_IFACE
  21 from zeroinstall.injector import qdom
  22
  23 # Element names for bindings in feed files
  24 binding_names = frozenset(['environment', 'overlay', 'executable-in-path', 'executable-in-var'])
  25
  26 network_offline = 'off-line'
  27 network_minimal = 'minimal'
  28 network_full = 'full'
  29 network_levels = (network_offline, network_minimal, network_full)
  30
  31 stability_levels = {}   # Name -> Stability
  32
  33 defaults = {
  34         'PATH': '/bin:/usr/bin',
  35         'XDG_CONFIG_DIRS': '/etc/xdg',
  36         'XDG_DATA_DIRS': '/usr/local/share:/usr/share',
  37 }
  38
  39 class InvalidInterface(SafeException):
  40         """Raised when parsing an invalid feed."""
  41         feed_url = None
  42
  43         def __init__(self, message, ex = None):
  44                 if ex:
  45                         try:
  46                                 message += "\n\n(exact error: %s)" % ex
  47                         except:
  48                                 # Some Python messages have type str but contain UTF-8 sequences.
  49                                 # (e.g. IOException). Adding these to a Unicode 'message' (e.g.
  50                                 # after gettext translation) will cause an error.
  51                                 import codecs
  52                                 decoder = codecs.lookup('utf-8')
  53                                 decex = decoder.decode(str(ex), errors = 'replace')[0]
  54                                 message += "\n\n(exact error: %s)" % decex
  55
  56                 SafeException.__init__(self, message)
  57
  58         def __unicode__(self):
  59                 if hasattr(SafeException, '__unicode__'):
  60                         # Python >= 2.6
  61                         if self.feed_url:
  62                                 return _('%s [%s]') % (SafeException.__unicode__(self), self.feed_url)
  63                         return SafeException.__unicode__(self)
  64                 else:
  65                         return unicode(SafeException.__str__(self))
  66
  67 def _split_arch(arch):
  68         """Split an arch into an (os, machine) tuple. Either or both parts may be None."""
  69         if not arch:
  70                 return None, None
  71         elif '-' not in arch:
  72                 raise SafeException(_("Malformed arch '%s'") % arch)
  73         else:
  74                 osys, machine = arch.split('-', 1)
  75                 if osys == '*': osys = None
  76                 if machine == '*': machine = None
  77                 return osys, machine
  78
  79 def _join_arch(osys, machine):
  80         if osys == machine == None: return None
  81         return "%s-%s" % (osys or '*', machine or '*')
  82
  83 def _best_language_match(options):
  84         (language, encoding) = locale.getlocale()
  85
  86         if language:
  87                 # xml:lang uses '-', while LANG uses '_'
  88                 language = language.replace('_', '-')
  89         else:
  90                 language = 'en-US'
  91
  92         return (options.get(language, None) or                  # Exact match (language+region)
  93                 options.get(language.split('-', 1)[0], None) or # Matching language
  94                 options.get('en', None))                        # English
  95
  96 class Stability(object):
  97         """A stability rating. Each implementation has an upstream stability rating and,
  98         optionally, a user-set rating."""
  99         __slots__ = ['level', 'name', 'description']
 100         def __init__(self, level, name, description):
 101                 self.level = level
 102                 self.name = name
 103                 self.description = description
 104                 assert name not in stability_levels
 105                 stability_levels[name] = self
 106
 107         def __cmp__(self, other):
 108                 return cmp(self.level, other.level)
 109
 110         def __str__(self):
 111                 return self.name
 112
 113         def __repr__(self):
 114                 return _("<Stability: %s>") % self.description
 115
 116 def process_binding(e):
 117         """Internal"""
 118         if e.name == 'environment':
 119                 mode = {
 120                         None: EnvironmentBinding.PREPEND,
 121                         'prepend': EnvironmentBinding.PREPEND,
 122                         'append': EnvironmentBinding.APPEND,
 123                         'replace': EnvironmentBinding.REPLACE,
 124                 }[e.getAttribute('mode')]
 125
 126                 binding = EnvironmentBinding(e.getAttribute('name'),
 127                                              insert = e.getAttribute('insert'),
 128                                              default = e.getAttribute('default'),
 129                                              value = e.getAttribute('value'),
 130                                              mode = mode,
 131                                              separator = e.getAttribute('separator'))
 132                 if not binding.name: raise InvalidInterface(_("Missing 'name' in binding"))
 133                 if binding.insert is None and binding.value is None:
 134                         raise InvalidInterface(_("Missing 'insert' or 'value' in binding"))
 135                 if binding.insert is not None and binding.value is not None:
 136                         raise InvalidInterface(_("Binding contains both 'insert' and 'value'"))
 137                 return binding
 138         elif e.name == 'executable-in-path':
 139                 return ExecutableBinding(e, in_path = True)
 140         elif e.name == 'executable-in-var':
 141                 return ExecutableBinding(e, in_path = False)
 142         elif e.name == 'overlay':
 143                 return OverlayBinding(e.getAttribute('src'), e.getAttribute('mount-point'))
 144         else:
 145                 raise Exception(_("Unknown binding type '%s'") % e.name)
 146
 147 def process_depends(item, local_feed_dir):
 148         """Internal"""
 149         # Note: also called from selections
 150         attrs = item.attrs
 151         dep_iface = item.getAttribute('interface')
 152         if not dep_iface:
 153                 raise InvalidInterface(_("Missing 'interface' on <%s>") % item.name)
 154         if dep_iface.startswith('./'):
 155                 if local_feed_dir:
 156                         dep_iface = os.path.abspath(os.path.join(local_feed_dir, dep_iface))
 157                         # (updates the element too, in case we write it out again)
 158                         attrs['interface'] = dep_iface
 159                 else:
 160                         raise InvalidInterface(_('Relative interface URI "%s" in non-local feed') % dep_iface)
 161         dependency = InterfaceDependency(dep_iface, element = item)
 162
 163         for e in item.childNodes:
 164                 if e.uri != XMLNS_IFACE: continue
 165                 if e.name in binding_names:
 166                         dependency.bindings.append(process_binding(e))
 167                 elif e.name == 'version':
 168                         dependency.restrictions.append(
 169                                 VersionRangeRestriction(not_before = parse_version(e.getAttribute('not-before')),
 170                                                         before = parse_version(e.getAttribute('before'))))
 171         return dependency
 172
 173 def N_(message): return message
 174
 175 insecure = Stability(0, N_('insecure'), _('This is a security risk'))
 176 buggy = Stability(5, N_('buggy'), _('Known to have serious bugs'))
 177 developer = Stability(10, N_('developer'), _('Work-in-progress - bugs likely'))
 178 testing = Stability(20, N_('testing'), _('Stability unknown - please test!'))
 179 stable = Stability(30, N_('stable'), _('Tested - no serious problems found'))
 180 packaged = Stability(35, N_('packaged'), _('Supplied by the local package manager'))
 181 preferred = Stability(40, N_('preferred'), _('Best of all - must be set manually'))
 182
 183 del N_
 184
 185 class Restriction(object):
 186         """A Restriction limits the allowed implementations of an Interface."""
 187         __slots__ = []
 188
 189         def meets_restriction(self, impl):
 190                 """Called by the L{solver.Solver} to check whether a particular implementation is acceptable.
 191                 @return: False if this implementation is not a possibility
 192                 @rtype: bool
 193                 """
 194                 raise NotImplementedError(_("Abstract"))
 195
 196 class VersionRestriction(Restriction):
 197         """Only select implementations with a particular version number.
 198         @since: 0.40"""
 199
 200         def __init__(self, version):
 201                 """@param version: the required version number
 202                 @see: L{parse_version}; use this to pre-process the version number
 203                 """
 204                 self.version = version
 205
 206         def meets_restriction(self, impl):
 207                 return impl.version == self.version
 208
 209         def __str__(self):
 210                 return _("(restriction: version = %s)") % format_version(self.version)
 211
 212 class VersionRangeRestriction(Restriction):
 213         """Only versions within the given range are acceptable"""
 214         __slots__ = ['before', 'not_before']
 215
 216         def __init__(self, before, not_before):
 217                 """@param before: chosen versions must be earlier than this
 218                 @param not_before: versions must be at least this high
 219                 @see: L{parse_version}; use this to pre-process the versions
 220                 """
 221                 self.before = before
 222                 self.not_before = not_before
 223
 224         def meets_restriction(self, impl):
 225                 if self.not_before and impl.version < self.not_before:
 226                         return False
 227                 if self.before and impl.version >= self.before:
 228                         return False
 229                 return True
 230
 231         def __str__(self):
 232                 if self.not_before is not None or self.before is not None:
 233                         range = ''
 234                         if self.not_before is not None:
 235                                 range += format_version(self.not_before) + ' <= '
 236                         range += 'version'
 237                         if self.before is not None:
 238                                 range += ' < ' + format_version(self.before)
 239                 else:
 240                         range = 'none'
 241                 return _("(restriction: %s)") % range
 242
 243 class Binding(object):
 244         """Information about how the choice of a Dependency is made known
 245         to the application being run."""
 246
 247         @property
 248         def command(self):
 249                 """"Returns the name of the specific command needed by this binding, if any.
 250                 @since: 1.2"""
 251                 return None
 252
 253 class EnvironmentBinding(Binding):
 254         """Indicate the chosen implementation using an environment variable."""
 255         __slots__ = ['name', 'insert', 'default', 'mode', 'value']
 256
 257         PREPEND = 'prepend'
 258         APPEND = 'append'
 259         REPLACE = 'replace'
 260
 261         def __init__(self, name, insert, default = None, mode = PREPEND, value=None, separator=None):
 262                 """
 263                 mode argument added in version 0.28
 264                 value argument added in version 0.52
 265                 """
 266                 self.name = name
 267                 self.insert = insert
 268                 self.default = default
 269                 self.mode = mode
 270                 self.value = value
 271                 if separator is None:
 272                         self.separator = os.pathsep
 273                 else:
 274                         self.separator = separator
 275
 276
 277         def __str__(self):
 278                 return _("<environ %(name)s %(mode)s %(insert)s %(value)s>") % \
 279                         {'name': self.name, 'mode': self.mode, 'insert': self.insert, 'value': self.value}
 280
 281         __repr__ = __str__
 282
 283         def get_value(self, path, old_value):
 284                 """Calculate the new value of the environment variable after applying this binding.
 285                 @param path: the path to the selected implementation
 286                 @param old_value: the current value of the environment variable
 287                 @return: the new value for the environment variable"""
 288
 289                 if self.insert is not None:
 290                         extra = os.path.join(path, self.insert)
 291                 else:
 292                         assert self.value is not None
 293                         extra = self.value
 294
 295                 if self.mode == EnvironmentBinding.REPLACE:
 296                         return extra
 297
 298                 if old_value is None:
 299                         old_value = self.default or defaults.get(self.name, None)
 300                 if old_value is None:
 301                         return extra
 302                 if self.mode == EnvironmentBinding.PREPEND:
 303                         return extra + self.separator + old_value
 304                 else:
 305                         return old_value + self.separator + extra
 306
 307         def _toxml(self, doc, prefixes):
 308                 """Create a DOM element for this binding.
 309                 @param doc: document to use to create the element
 310                 @return: the new element
 311                 """
 312                 env_elem = doc.createElementNS(XMLNS_IFACE, 'environment')
 313                 env_elem.setAttributeNS(None, 'name', self.name)
 314                 if self.mode is not None:
 315                         env_elem.setAttributeNS(None, 'mode', self.mode)
 316                 if self.insert is not None:
 317                         env_elem.setAttributeNS(None, 'insert', self.insert)
 318                 else:
 319                         env_elem.setAttributeNS(None, 'value', self.value)
 320                 if self.default:
 321                         env_elem.setAttributeNS(None, 'default', self.default)
 322                 if self.separator:
 323                         env_elem.setAttributeNS(None, 'separator', self.separator)
 324                 return env_elem
 325
 326 class ExecutableBinding(Binding):
 327         """Make the chosen command available in $PATH.
 328         @ivar in_path: True to add the named command to $PATH, False to store in named variable
 329         @type in_path: bool
 330         """
 331         __slots__ = ['qdom']
 332
 333         def __init__(self, qdom, in_path):
 334                 self.qdom = qdom
 335                 self.in_path = in_path
 336
 337         def __str__(self):
 338                 return str(self.qdom)
 339
 340         __repr__ = __str__
 341
 342         def _toxml(self, doc, prefixes):
 343                 return self.qdom.toDOM(doc, prefixes)
 344
 345         @property
 346         def name(self):
 347                 return self.qdom.getAttribute('name')
 348
 349         @property
 350         def command(self):
 351                 return self.qdom.getAttribute("command") or 'run'
 352
 353 class OverlayBinding(Binding):
 354         """Make the chosen implementation available by overlaying it onto another part of the file-system.
 355         This is to support legacy programs which use hard-coded paths."""
 356         __slots__ = ['src', 'mount_point']
 357
 358         def __init__(self, src, mount_point):
 359                 self.src = src
 360                 self.mount_point = mount_point
 361
 362         def __str__(self):
 363                 return _("<overlay %(src)s on %(mount_point)s>") % {'src': self.src or '.', 'mount_point': self.mount_point or '/'}
 364
 365         __repr__ = __str__
 366
 367         def _toxml(self, doc, prefixes):
 368                 """Create a DOM element for this binding.
 369                 @param doc: document to use to create the element
 370                 @return: the new element
 371                 """
 372                 env_elem = doc.createElementNS(XMLNS_IFACE, 'overlay')
 373                 if self.src is not None:
 374                         env_elem.setAttributeNS(None, 'src', self.src)
 375                 if self.mount_point is not None:
 376                         env_elem.setAttributeNS(None, 'mount-point', self.mount_point)
 377                 return env_elem
 378
 379 class Feed(object):
 380         """An interface's feeds are other interfaces whose implementations can also be
 381         used as implementations of this interface."""
 382         __slots__ = ['uri', 'os', 'machine', 'user_override', 'langs']
 383         def __init__(self, uri, arch, user_override, langs = None):
 384                 self.uri = uri
 385                 # This indicates whether the feed comes from the user's overrides
 386                 # file. If true, writer.py will write it when saving.
 387                 self.user_override = user_override
 388                 self.os, self.machine = _split_arch(arch)
 389                 self.langs = langs
 390
 391         def __str__(self):
 392                 return "<Feed from %s>" % self.uri
 393         __repr__ = __str__
 394
 395         arch = property(lambda self: _join_arch(self.os, self.machine))
 396
 397 class Dependency(object):
 398         """A Dependency indicates that an Implementation requires some additional
 399         code to function. This is an abstract base class.
 400         @ivar qdom: the XML element for this Dependency (since 0launch 0.51)
 401         @type qdom: L{qdom.Element}
 402         @ivar metadata: any extra attributes from the XML element
 403         @type metadata: {str: str}
 404         """
 405         __slots__ = ['qdom']
 406
 407         Essential = "essential"
 408         Recommended = "recommended"
 409
 410         def __init__(self, element):
 411                 assert isinstance(element, qdom.Element), type(element) # Use InterfaceDependency instead!
 412                 self.qdom = element
 413
 414         @property
 415         def metadata(self):
 416                 return self.qdom.attrs
 417
 418         @property
 419         def importance(self):
 420                 return self.qdom.getAttribute("importance") or Dependency.Essential
 421
 422         def get_required_commands(self):
 423                 """Return a list of command names needed by this dependency"""
 424                 return []
 425
 426 class InterfaceDependency(Dependency):
 427         """A Dependency on a Zero Install interface.
 428         @ivar interface: the interface required by this dependency
 429         @type interface: str
 430         @ivar restrictions: a list of constraints on acceptable implementations
 431         @type restrictions: [L{Restriction}]
 432         @ivar bindings: how to make the choice of implementation known
 433         @type bindings: [L{Binding}]
 434         @since: 0.28
 435         """
 436         __slots__ = ['interface', 'restrictions', 'bindings']
 437
 438         def __init__(self, interface, restrictions = None, element = None):
 439                 Dependency.__init__(self, element)
 440                 assert isinstance(interface, (str, unicode))
 441                 assert interface
 442                 self.interface = interface
 443                 if restrictions is None:
 444                         self.restrictions = []
 445                 else:
 446                         self.restrictions = restrictions
 447                 self.bindings = []
 448
 449         def __str__(self):
 450                 return _("<Dependency on %(interface)s; bindings: %(bindings)s%(restrictions)s>") % {'interface': self.interface, 'bindings': self.bindings, 'restrictions': self.restrictions}
 451
 452         def get_required_commands(self):
 453                 """Return a list of command names needed by this dependency"""
 454                 if self.qdom.name == 'runner':
 455                         commands = [self.qdom.getAttribute('command') or 'run']
 456                 else:
 457                         commands = []
 458                 for b in self.bindings:
 459                         c = b.command
 460                         if c is not None:
 461                                 commands.append(c)
 462                 return commands
 463
 464         @property
 465         def command(self):
 466                 if self.qdom.name == 'runner':
 467                         return self.qdom.getAttribute('command') or 'run'
 468                 return None
 469
 470 class RetrievalMethod(object):
 471         """A RetrievalMethod provides a way to fetch an implementation."""
 472         __slots__ = []
 473
 474 class DownloadSource(RetrievalMethod):
 475         """A DownloadSource provides a way to fetch an implementation."""
 476         __slots__ = ['implementation', 'url', 'size', 'extract', 'start_offset', 'type']
 477
 478         def __init__(self, implementation, url, size, extract, start_offset = 0, type = None):
 479                 self.implementation = implementation
 480                 self.url = url
 481                 self.size = size
 482                 self.extract = extract
 483                 self.start_offset = start_offset
 484                 self.type = type                # MIME type - see unpack.py
 485
 486 class Recipe(RetrievalMethod):
 487         """Get an implementation by following a series of steps.
 488         @ivar size: the combined download sizes from all the steps
 489         @type size: int
 490         @ivar steps: the sequence of steps which must be performed
 491         @type steps: [L{RetrievalMethod}]"""
 492         __slots__ = ['steps']
 493
 494         def __init__(self):
 495                 self.steps = []
 496
 497         size = property(lambda self: sum([x.size for x in self.steps]))
 498
 499 class DistributionSource(RetrievalMethod):
 500         """A package that is installed using the distribution's tools (including PackageKit).
 501         @ivar install: a function to call to install this package
 502         @type install: (L{handler.Handler}) -> L{tasks.Blocker}
 503         @ivar package_id: the package name, in a form recognised by the distribution's tools
 504         @type package_id: str
 505         @ivar size: the download size in bytes
 506         @type size: int
 507         @ivar needs_confirmation: whether the user should be asked to confirm before calling install()
 508         @type needs_confirmation: bool"""
 509
 510         __slots__ = ['package_id', 'size', 'install', 'needs_confirmation']
 511
 512         def __init__(self, package_id, size, install, needs_confirmation = True):
 513                 RetrievalMethod.__init__(self)
 514                 self.package_id = package_id
 515                 self.size = size
 516                 self.install = install
 517                 self.needs_confirmation = needs_confirmation
 518
 519 class Command(object):
 520         """A Command is a way of running an Implementation as a program."""
 521
 522         __slots__ = ['qdom', '_depends', '_local_dir', '_runner', '_bindings']
 523
 524         def __init__(self, qdom, local_dir):
 525                 """@param qdom: the <command> element
 526                 @param local_dir: the directory containing the feed (for relative dependencies), or None if not local
 527                 """
 528                 assert qdom.name == 'command', 'not <command>: %s' % qdom
 529                 self.qdom = qdom
 530                 self._local_dir = local_dir
 531                 self._depends = None
 532                 self._bindings = None
 533
 534         path = property(lambda self: self.qdom.attrs.get("path", None))
 535
 536         def _toxml(self, doc, prefixes):
 537                 return self.qdom.toDOM(doc, prefixes)
 538
 539         @property
 540         def requires(self):
 541                 if self._depends is None:
 542                         self._runner = None
 543                         depends = []
 544                         for child in self.qdom.childNodes:
 545                                 if child.name == 'requires':
 546                                         dep = process_depends(child, self._local_dir)
 547                                         depends.append(dep)
 548                                 elif child.name == 'runner':
 549                                         if self._runner:
 550                                                 raise InvalidInterface(_("Multiple <runner>s in <command>!"))
 551                                         dep = process_depends(child, self._local_dir)
 552                                         depends.append(dep)
 553                                         self._runner = dep
 554                         self._depends = depends
 555                 return self._depends
 556
 557         def get_runner(self):
 558                 self.requires           # (sets _runner)
 559                 return self._runner
 560
 561         def __str__(self):
 562                 return str(self.qdom)
 563
 564         @property
 565         def bindings(self):
 566                 """@since: 1.3"""
 567                 if self._bindings is None:
 568                         bindings = []
 569                         for e in self.qdom.childNodes:
 570                                 if e.uri != XMLNS_IFACE: continue
 571                                 if e.name in binding_names:
 572                                         bindings.append(process_binding(e))
 573                         self._bindings = bindings
 574                 return self._bindings
 575
 576 class Implementation(object):
 577         """An Implementation is a package which implements an Interface.
 578         @ivar download_sources: list of methods of getting this implementation
 579         @type download_sources: [L{RetrievalMethod}]
 580         @ivar feed: the feed owning this implementation (since 0.32)
 581         @type feed: [L{ZeroInstallFeed}]
 582         @ivar bindings: how to tell this component where it itself is located (since 0.31)
 583         @type bindings: [Binding]
 584         @ivar upstream_stability: the stability reported by the packager
 585         @type upstream_stability: [insecure | buggy | developer | testing | stable | packaged]
 586         @ivar user_stability: the stability as set by the user
 587         @type upstream_stability: [insecure | buggy | developer | testing | stable | packaged | preferred]
 588         @ivar langs: natural languages supported by this package
 589         @type langs: str
 590         @ivar requires: interfaces this package depends on
 591         @type requires: [L{Dependency}]
 592         @ivar commands: ways to execute as a program
 593         @type commands: {str: Command}
 594         @ivar metadata: extra metadata from the feed
 595         @type metadata: {"[URI ]localName": str}
 596         @ivar id: a unique identifier for this Implementation
 597         @ivar version: a parsed version number
 598         @ivar released: release date
 599         @ivar local_path: the directory containing this local implementation, or None if it isn't local (id isn't a path)
 600         @type local_path: str | None
 601         @ivar requires_root_install: whether the user will need admin rights to use this
 602         @type requires_root_install: bool
 603         """
 604
 605         # Note: user_stability shouldn't really be here
 606
 607         __slots__ = ['upstream_stability', 'user_stability', 'langs',
 608                      'requires', 'metadata', 'download_sources', 'commands',
 609                      'id', 'feed', 'version', 'released', 'bindings', 'machine']
 610
 611         def __init__(self, feed, id):
 612                 assert id
 613                 self.feed = feed
 614                 self.id = id
 615                 self.user_stability = None
 616                 self.upstream_stability = None
 617                 self.metadata = {}      # [URI + " "] + localName -> value
 618                 self.requires = []
 619                 self.version = None
 620                 self.released = None
 621                 self.download_sources = []
 622                 self.langs = ""
 623                 self.machine = None
 624                 self.bindings = []
 625                 self.commands = {}
 626
 627         def get_stability(self):
 628                 return self.user_stability or self.upstream_stability or testing
 629
 630         def __str__(self):
 631                 return self.id
 632
 633         def __repr__(self):
 634                 return "v%s (%s)" % (self.get_version(), self.id)
 635
 636         def __cmp__(self, other):
 637                 """Newer versions come first"""
 638                 d = cmp(other.version, self.version)
 639                 if d: return d
 640                 # If the version number is the same, just give a stable sort order, and
 641                 # ensure that two different implementations don't compare equal.
 642                 d = cmp(other.feed.url, self.feed.url)
 643                 if d: return d
 644                 return cmp(other.id, self.id)
 645
 646         def get_version(self):
 647                 """Return the version as a string.
 648                 @see: L{format_version}
 649                 """
 650                 return format_version(self.version)
 651
 652         arch = property(lambda self: _join_arch(self.os, self.machine))
 653
 654         os = None
 655         local_path = None
 656         digests = None
 657         requires_root_install = False
 658
 659         def _get_main(self):
 660                 """"@deprecated: use commands["run"] instead"""
 661                 main = self.commands.get("run", None)
 662                 if main is not None:
 663                         return main.path
 664                 return None
 665         def _set_main(self, path):
 666                 """"@deprecated: use commands["run"] instead"""
 667                 if path is None:
 668                         if "run" in self.commands:
 669                                 del self.commands["run"]
 670                 else:
 671                         self.commands["run"] = Command(qdom.Element(XMLNS_IFACE, 'command', {'path': path, 'name': 'run'}), None)
 672         main = property(_get_main, _set_main)
 673
 674         def is_available(self, stores):
 675                 """Is this Implementation available locally?
 676                 (a local implementation, an installed distribution package, or a cached ZeroInstallImplementation)
 677                 @rtype: bool
 678                 @since: 0.53
 679                 """
 680                 raise NotImplementedError("abstract")
 681
 682 # Calculates "path" lazily, since it may involve searching the file system
 683 class _DistributionCommand(Command):
 684         __slots__ = ['impl', '_path']
 685
 686         def __init__(self, impl, qdom):
 687                 Command.__init__(self, qdom, None)
 688                 self.impl = impl
 689                 self._path = False      # lazy
 690
 691         @property
 692         def path(self):
 693                 if self._path is False:
 694                         self._path = self.qdom.attrs.get("path", None)
 695                         if self._path is None:
 696                                 pattern = self.qdom.attrs.get("glob", None)
 697                                 if pattern:
 698                                         if not pattern.startswith('/'):
 699                                                 raise SafeException("Glob pattern '{glob}' should start with '/' (in feed {feed})".format(
 700                                                                         glob = pattern, feed = self.impl.feed.url))
 701                                         import glob
 702                                         matches = glob.glob(pattern)
 703                                         if len(matches) == 1:
 704                                                 self._path = matches[0]
 705                                         elif matches:
 706                                                 raise SafeException("Multiple matches for glob '{glob}'".format(glob = pattern))
 707                                         else:
 708                                                 raise SafeException("No matches for glob '{glob}'".format(glob = pattern))
 709                 return self._path
 710
 711
 712 class DistributionImplementation(Implementation):
 713         """An implementation provided by the distribution. Information such as the version
 714         comes from the package manager.
 715         @ivar package_implementation: the <package-implementation> element that generated this impl (since 1.7)
 716         @type package_implementation: L{qdom.Element}
 717         @since: 0.28"""
 718         __slots__ = ['distro', 'installed', 'package_implementation']
 719
 720         def __init__(self, feed, id, distro, package_implementation = None):
 721                 assert id.startswith('package:')
 722                 Implementation.__init__(self, feed, id)
 723                 self.distro = distro
 724                 self.installed = False
 725                 self.package_implementation = package_implementation
 726
 727                 if package_implementation:
 728                         for item in package_implementation.childNodes:
 729                                 if item.uri != XMLNS_IFACE: continue
 730                                 if item.name == 'command':
 731                                         self.commands[item.getAttribute("name")] = _DistributionCommand(self, item)
 732
 733         @property
 734         def requires_root_install(self):
 735                 return not self.installed
 736
 737         def is_available(self, stores):
 738                 return self.installed
 739
 740 class ZeroInstallImplementation(Implementation):
 741         """An implementation where all the information comes from Zero Install.
 742         @ivar digests: a list of "algorith=value" strings (since 0.45)
 743         @type digests: [str]
 744         @since: 0.28"""
 745         __slots__ = ['os', 'size', 'digests', 'local_path']
 746
 747         def __init__(self, feed, id, local_path):
 748                 """id can be a local path (string starting with /) or a manifest hash (eg "sha1=XXX")"""
 749                 assert not id.startswith('package:'), id
 750                 Implementation.__init__(self, feed, id)
 751                 self.size = None
 752                 self.os = None
 753                 self.digests = []
 754                 self.local_path = local_path
 755
 756         # Deprecated
 757         dependencies = property(lambda self: dict([(x.interface, x) for x in self.requires
 758                                                    if isinstance(x, InterfaceDependency)]))
 759
 760         def add_download_source(self, url, size, extract, start_offset = 0, type = None):
 761                 """Add a download source."""
 762                 self.download_sources.append(DownloadSource(self, url, size, extract, start_offset, type))
 763
 764         def set_arch(self, arch):
 765                 self.os, self.machine = _split_arch(arch)
 766         arch = property(lambda self: _join_arch(self.os, self.machine), set_arch)
 767
 768         def is_available(self, stores):
 769                 if self.local_path is not None:
 770                         return os.path.exists(self.local_path)
 771                 if self.digests:
 772                         path = stores.lookup_maybe(self.digests)
 773                         return path is not None
 774                 return False    # (0compile creates fake entries with no digests)
 775
 776 class Interface(object):
 777         """An Interface represents some contract of behaviour.
 778         @ivar uri: the URI for this interface.
 779         @ivar stability_policy: user's configured policy.
 780         Implementations at this level or higher are preferred.
 781         Lower levels are used only if there is no other choice.
 782         """
 783         __slots__ = ['uri', 'stability_policy', 'extra_feeds']
 784
 785         implementations = property(lambda self: self._main_feed.implementations)
 786         name = property(lambda self: self._main_feed.name)
 787         description = property(lambda self: self._main_feed.description)
 788         summary = property(lambda self: self._main_feed.summary)
 789         last_modified = property(lambda self: self._main_feed.last_modified)
 790         feeds = property(lambda self: self.extra_feeds + self._main_feed.feeds)
 791         metadata = property(lambda self: self._main_feed.metadata)
 792
 793         last_checked = property(lambda self: self._main_feed.last_checked)
 794
 795         def __init__(self, uri):
 796                 assert uri
 797                 if uri.startswith('http:') or uri.startswith('https:') or os.path.isabs(uri):
 798                         self.uri = uri
 799                 else:
 800                         raise SafeException(_("Interface name '%s' doesn't start "
 801                                             "with 'http:' or 'https:'") % uri)
 802                 self.reset()
 803
 804         def _get_feed_for(self):
 805                 retval = {}
 806                 for key in self._main_feed.feed_for:
 807                         retval[key] = True
 808                 return retval
 809         feed_for = property(_get_feed_for)      # Deprecated (used by 0publish)
 810
 811         def reset(self):
 812                 self.extra_feeds = []
 813                 self.stability_policy = None
 814
 815         def get_name(self):
 816                 from zeroinstall.injector.iface_cache import iface_cache
 817                 feed = iface_cache.get_feed(self.uri)
 818                 if feed:
 819                         return feed.get_name()
 820                 return '(' + os.path.basename(self.uri) + ')'
 821
 822         def __repr__(self):
 823                 return _("<Interface %s>") % self.uri
 824
 825         def set_stability_policy(self, new):
 826                 assert new is None or isinstance(new, Stability)
 827                 self.stability_policy = new
 828
 829         def get_feed(self, url):
 830                 #import warnings
 831                 #warnings.warn("use iface_cache.get_feed instead", DeprecationWarning, 2)
 832                 for x in self.extra_feeds:
 833                         if x.uri == url:
 834                                 return x
 835                 #return self._main_feed.get_feed(url)
 836                 return None
 837
 838         def get_metadata(self, uri, name):
 839                 return self._main_feed.get_metadata(uri, name)
 840
 841         @property
 842         def _main_feed(self):
 843                 #import warnings
 844                 #warnings.warn("use the feed instead", DeprecationWarning, 3)
 845                 from zeroinstall.injector import policy
 846                 iface_cache = policy.get_deprecated_singleton_config().iface_cache
 847                 feed = iface_cache.get_feed(self.uri)
 848                 if feed is None:
 849                         return _dummy_feed
 850                 return feed
 851
 852 def _merge_attrs(attrs, item):
 853         """Add each attribute of item to a copy of attrs and return the copy.
 854         @type attrs: {str: str}
 855         @type item: L{qdom.Element}
 856         @rtype: {str: str}
 857         """
 858         new = attrs.copy()
 859         for a in item.attrs:
 860                 new[str(a)] = item.attrs[a]
 861         return new
 862
 863 def _get_long(elem, attr_name):
 864         val = elem.getAttribute(attr_name)
 865         if val is not None:
 866                 try:
 867                         val = int(val)
 868                 except ValueError:
 869                         raise SafeException(_("Invalid value for integer attribute '%(attribute_name)s': %(value)s") % {'attribute_name': attr_name, 'value': val})
 870         return val
 871
 872 class ZeroInstallFeed(object):
 873         """A feed lists available implementations of an interface.
 874         @ivar url: the URL for this feed
 875         @ivar implementations: Implementations in this feed, indexed by ID
 876         @type implementations: {str: L{Implementation}}
 877         @ivar name: human-friendly name
 878         @ivar summaries: short textual description (in various languages, since 0.49)
 879         @type summaries: {str: str}
 880         @ivar descriptions: long textual description (in various languages, since 0.49)
 881         @type descriptions: {str: str}
 882         @ivar last_modified: timestamp on signature
 883         @ivar last_checked: time feed was last successfully downloaded and updated
 884         @ivar local_path: the path of this local feed, or None if remote (since 1.7)
 885         @type local_path: str | None
 886         @ivar feeds: list of <feed> elements in this feed
 887         @type feeds: [L{Feed}]
 888         @ivar feed_for: interfaces for which this could be a feed
 889         @type feed_for: set(str)
 890         @ivar metadata: extra elements we didn't understand
 891         """
 892         # _main is deprecated
 893         __slots__ = ['url', 'implementations', 'name', 'descriptions', 'first_description', 'summaries', 'first_summary', '_package_implementations',
 894                      'last_checked', 'last_modified', 'feeds', 'feed_for', 'metadata', 'local_path']
 895
 896         def __init__(self, feed_element, local_path = None, distro = None):
 897                 """Create a feed object from a DOM.
 898                 @param feed_element: the root element of a feed file
 899                 @type feed_element: L{qdom.Element}
 900                 @param local_path: the pathname of this local feed, or None for remote feeds"""
 901                 self.local_path = local_path
 902                 self.implementations = {}
 903                 self.name = None
 904                 self.summaries = {}     # { lang: str }
 905                 self.first_summary = None
 906                 self.descriptions = {}  # { lang: str }
 907                 self.first_description = None
 908                 self.last_modified = None
 909                 self.feeds = []
 910                 self.feed_for = set()
 911                 self.metadata = []
 912                 self.last_checked = None
 913                 self._package_implementations = []
 914
 915                 if distro is not None:
 916                         import warnings
 917                         warnings.warn("distro argument is now ignored", DeprecationWarning, 2)
 918
 919                 if feed_element is None:
 920                         return                  # XXX subclass?
 921
 922                 assert feed_element.name in ('interface', 'feed'), "Root element should be <interface>, not %s" % feed_element
 923                 assert feed_element.uri == XMLNS_IFACE, "Wrong namespace on root element: %s" % feed_element.uri
 924
 925                 main = feed_element.getAttribute('main')
 926                 #if main: warn("Setting 'main' on the root element is deprecated. Put it on a <group> instead")
 927
 928                 if local_path:
 929                         self.url = local_path
 930                         local_dir = os.path.dirname(local_path)
 931                 else:
 932                         assert local_path is None
 933                         self.url = feed_element.getAttribute('uri')
 934                         if not self.url:
 935                                 raise InvalidInterface(_("<interface> uri attribute missing"))
 936                         local_dir = None        # Can't have relative paths
 937
 938                 min_injector_version = feed_element.getAttribute('min-injector-version')
 939                 if min_injector_version:
 940                         if parse_version(min_injector_version) > parse_version(version):
 941                                 raise InvalidInterface(_("This feed requires version %(min_version)s or later of "
 942                                                         "Zero Install, but I am only version %(version)s. "
 943                                                         "You can get a newer version from http://0install.net") %
 944                                                         {'min_version': min_injector_version, 'version': version})
 945
 946                 for x in feed_element.childNodes:
 947                         if x.uri != XMLNS_IFACE:
 948                                 self.metadata.append(x)
 949                                 continue
 950                         if x.name == 'name':
 951                                 self.name = x.content
 952                         elif x.name == 'description':
 953                                 if self.first_description == None:
 954                                         self.first_description = x.content
 955                                 self.descriptions[x.attrs.get("http://www.w3.org/XML/1998/namespace lang", 'en')] = x.content
 956                         elif x.name == 'summary':
 957                                 if self.first_summary == None:
 958                                         self.first_summary = x.content
 959                                 self.summaries[x.attrs.get("http://www.w3.org/XML/1998/namespace lang", 'en')] = x.content
 960                         elif x.name == 'feed-for':
 961                                 feed_iface = x.getAttribute('interface')
 962                                 if not feed_iface:
 963                                         raise InvalidInterface(_('Missing "interface" attribute in <feed-for>'))
 964                                 self.feed_for.add(feed_iface)
 965                                 # Bug report from a Debian/stable user that --feed gets the wrong value.
 966                                 # Can't reproduce (even in a Debian/stable chroot), but add some logging here
 967                                 # in case it happens again.
 968                                 debug(_("Is feed-for %s"), feed_iface)
 969                         elif x.name == 'feed':
 970                                 feed_src = x.getAttribute('src')
 971                                 if not feed_src:
 972                                         raise InvalidInterface(_('Missing "src" attribute in <feed>'))
 973                                 if feed_src.startswith('http:') or feed_src.startswith('https:') or local_path:
 974                                         langs = x.getAttribute('langs')
 975                                         if langs: langs = langs.replace('_', '-')
 976                                         self.feeds.append(Feed(feed_src, x.getAttribute('arch'), False, langs = langs))
 977                                 else:
 978                                         raise InvalidInterface(_("Invalid feed URL '%s'") % feed_src)
 979                         else:
 980                                 self.metadata.append(x)
 981
 982                 if not self.name:
 983                         raise InvalidInterface(_("Missing <name> in feed"))
 984                 if not self.summary:
 985                         raise InvalidInterface(_("Missing <summary> in feed"))
 986
 987                 def process_group(group, group_attrs, base_depends, base_bindings, base_commands):
 988                         for item in group.childNodes:
 989                                 if item.uri != XMLNS_IFACE: continue
 990
 991                                 if item.name not in ('group', 'implementation', 'package-implementation'):
 992                                         continue
 993
 994                                 # We've found a group or implementation. Scan for dependencies,
 995                                 # bindings and commands. Doing this here means that:
 996                                 # - We can share the code for groups and implementations here.
 997                                 # - The order doesn't matter, because these get processed first.
 998                                 # A side-effect is that the document root cannot contain
 999                                 # these.
1000
1001                                 depends = base_depends[:]
1002                                 bindings = base_bindings[:]
1003                                 commands = base_commands.copy()
1004
1005                                 for attr, command in [('main', 'run'),
1006                                                       ('self-test', 'test')]:
1007                                         value = item.attrs.get(attr, None)
1008                                         if value is not None:
1009                                                 commands[command] = Command(qdom.Element(XMLNS_IFACE, 'command', {'name': command, 'path': value}), None)
1010
1011                                 for child in item.childNodes:
1012                                         if child.uri != XMLNS_IFACE: continue
1013                                         if child.name == 'requires':
1014                                                 dep = process_depends(child, local_dir)
1015                                                 depends.append(dep)
1016                                         elif child.name == 'command':
1017                                                 command_name = child.attrs.get('name', None)
1018                                                 if not command_name:
1019                                                         raise InvalidInterface('Missing name for <command>')
1020                                                 commands[command_name] = Command(child, local_dir)
1021                                         elif child.name in binding_names:
1022                                                 bindings.append(process_binding(child))
1023
1024                                 compile_command = item.attrs.get('http://zero-install.sourceforge.net/2006/namespaces/0compile command')
1025                                 if compile_command is not None:
1026                                         commands['compile'] = Command(qdom.Element(XMLNS_IFACE, 'command', {'name': 'compile', 'shell-command': compile_command}), None)
1027
1028                                 item_attrs = _merge_attrs(group_attrs, item)
1029
1030                                 if item.name == 'group':
1031                                         process_group(item, item_attrs, depends, bindings, commands)
1032                                 elif item.name == 'implementation':
1033                                         process_impl(item, item_attrs, depends, bindings, commands)
1034                                 elif item.name == 'package-implementation':
1035                                         if depends:
1036                                                 warn("A <package-implementation> with dependencies in %s!", self.url)
1037                                         self._package_implementations.append((item, item_attrs))
1038                                 else:
1039                                         assert 0
1040
1041                 def process_impl(item, item_attrs, depends, bindings, commands):
1042                         id = item.getAttribute('id')
1043                         if id is None:
1044                                 raise InvalidInterface(_("Missing 'id' attribute on %s") % item)
1045                         local_path = item_attrs.get('local-path')
1046                         if local_dir and local_path:
1047                                 abs_local_path = os.path.abspath(os.path.join(local_dir, local_path))
1048                                 impl = ZeroInstallImplementation(self, id, abs_local_path)
1049                         elif local_dir and (id.startswith('/') or id.startswith('.')):
1050                                 # For old feeds
1051                                 id = os.path.abspath(os.path.join(local_dir, id))
1052                                 impl = ZeroInstallImplementation(self, id, id)
1053                         else:
1054                                 impl = ZeroInstallImplementation(self, id, None)
1055                                 if '=' in id:
1056                                         # In older feeds, the ID was the (single) digest
1057                                         impl.digests.append(id)
1058                         if id in self.implementations:
1059                                 warn(_("Duplicate ID '%(id)s' in feed '%(feed)s'"), {'id': id, 'feed': self})
1060                         self.implementations[id] = impl
1061
1062                         impl.metadata = item_attrs
1063                         try:
1064                                 version_mod = item_attrs.get('version-modifier', None)
1065                                 if version_mod:
1066                                         item_attrs['version'] += version_mod
1067                                         del item_attrs['version-modifier']
1068                                 version = item_attrs['version']
1069                         except KeyError:
1070                                 raise InvalidInterface(_("Missing version attribute"))
1071                         impl.version = parse_version(version)
1072
1073                         impl.commands = commands
1074
1075                         impl.released = item_attrs.get('released', None)
1076                         impl.langs = item_attrs.get('langs', '').replace('_', '-')
1077
1078                         size = item.getAttribute('size')
1079                         if size:
1080                                 impl.size = int(size)
1081                         impl.arch = item_attrs.get('arch', None)
1082                         try:
1083                                 stability = stability_levels[str(item_attrs['stability'])]
1084                         except KeyError:
1085                                 stab = str(item_attrs['stability'])
1086                                 if stab != stab.lower():
1087                                         raise InvalidInterface(_('Stability "%s" invalid - use lower case!') % item_attrs.stability)
1088                                 raise InvalidInterface(_('Stability "%s" invalid') % item_attrs['stability'])
1089                         if stability >= preferred:
1090                                 raise InvalidInterface(_("Upstream can't set stability to preferred!"))
1091                         impl.upstream_stability = stability
1092
1093                         impl.bindings = bindings
1094                         impl.requires = depends
1095
1096                         for elem in item.childNodes:
1097                                 if elem.uri != XMLNS_IFACE: continue
1098                                 if elem.name == 'archive':
1099                                         url = elem.getAttribute('href')
1100                                         if not url:
1101                                                 raise InvalidInterface(_("Missing href attribute on <archive>"))
1102                                         size = elem.getAttribute('size')
1103                                         if not size:
1104                                                 raise InvalidInterface(_("Missing size attribute on <archive>"))
1105                                         impl.add_download_source(url = url, size = int(size),
1106                                                         extract = elem.getAttribute('extract'),
1107                                                         start_offset = _get_long(elem, 'start-offset'),
1108                                                         type = elem.getAttribute('type'))
1109                                 elif elem.name == 'manifest-digest':
1110                                         for aname, avalue in elem.attrs.iteritems():
1111                                                 if ' ' not in aname:
1112                                                         impl.digests.append('%s=%s' % (aname, avalue))
1113                                 elif elem.name == 'recipe':
1114                                         recipe = Recipe()
1115                                         for recipe_step in elem.childNodes:
1116                                                 if recipe_step.uri == XMLNS_IFACE and recipe_step.name == 'archive':
1117                                                         url = recipe_step.getAttribute('href')
1118                                                         if not url:
1119                                                                 raise InvalidInterface(_("Missing href attribute on <archive>"))
1120                                                         size = recipe_step.getAttribute('size')
1121                                                         if not size:
1122                                                                 raise InvalidInterface(_("Missing size attribute on <archive>"))
1123                                                         recipe.steps.append(DownloadSource(None, url = url, size = int(size),
1124                                                                         extract = recipe_step.getAttribute('extract'),
1125                                                                         start_offset = _get_long(recipe_step, 'start-offset'),
1126                                                                         type = recipe_step.getAttribute('type')))
1127                                                 else:
1128                                                         info(_("Unknown step '%s' in recipe; skipping recipe"), recipe_step.name)
1129                                                         break
1130                                         else:
1131                                                 impl.download_sources.append(recipe)
1132
1133                 root_attrs = {'stability': 'testing'}
1134                 root_commands = {}
1135                 if main:
1136                         info("Note: @main on document element is deprecated in %s", self)
1137                         root_commands['run'] = Command(qdom.Element(XMLNS_IFACE, 'command', {'path': main, 'name': 'run'}), None)
1138                 process_group(feed_element, root_attrs, [], [], root_commands)
1139
1140         def get_distro_feed(self):
1141                 """Does this feed contain any <pacakge-implementation> elements?
1142                 i.e. is it worth asking the package manager for more information?
1143                 @return: the URL of the virtual feed, or None
1144                 @since: 0.49"""
1145                 if self._package_implementations:
1146                         return "distribution:" + self.url
1147                 return None
1148
1149         def get_package_impls(self, distro):
1150                 """Find the best <pacakge-implementation> element(s) for the given distribution.
1151                 @param distro: the distribution to use to rate them
1152                 @type distro: L{distro.Distribution}
1153                 @return: a list of tuples for the best ranked elements
1154                 @rtype: [str]
1155                 @since: 0.49"""
1156                 best_score = 0
1157                 best_impls = []
1158
1159                 for item, item_attrs in self._package_implementations:
1160                         distro_names = item_attrs.get('distributions', '')
1161                         for distro_name in distro_names.split(' '):
1162                                 score = distro.get_score(distro_name)
1163                                 if score > best_score:
1164                                         best_score = score
1165                                         best_impls = []
1166                                 if score == best_score:
1167                                         best_impls.append((item, item_attrs))
1168                 return best_impls
1169
1170         def get_name(self):
1171                 return self.name or '(' + os.path.basename(self.url) + ')'
1172
1173         def __repr__(self):
1174                 return _("<Feed %s>") % self.url
1175
1176         def set_stability_policy(self, new):
1177                 assert new is None or isinstance(new, Stability)
1178                 self.stability_policy = new
1179
1180         def get_feed(self, url):
1181                 for x in self.feeds:
1182                         if x.uri == url:
1183                                 return x
1184                 return None
1185
1186         def add_metadata(self, elem):
1187                 self.metadata.append(elem)
1188
1189         def get_metadata(self, uri, name):
1190                 """Return a list of interface metadata elements with this name and namespace URI."""
1191                 return [m for m in self.metadata if m.name == name and m.uri == uri]
1192
1193         @property
1194         def summary(self):
1195                 return _best_language_match(self.summaries) or self.first_summary
1196
1197         @property
1198         def description(self):
1199                 return _best_language_match(self.descriptions) or self.first_description
1200
1201 class DummyFeed(object):
1202         """Temporary class used during API transition."""
1203         last_modified = None
1204         name = '-'
1205         last_checked = property(lambda self: None)
1206         implementations = property(lambda self: {})
1207         feeds = property(lambda self: [])
1208         summary = property(lambda self: '-')
1209         description = property(lambda self: '')
1210         def get_name(self): return self.name
1211         def get_feed(self, url): return None
1212         def get_metadata(self, uri, name): return []
1213 _dummy_feed = DummyFeed()
1214
1215 def unescape(uri):
1216         """Convert each %20 to a space, etc.
1217         @rtype: str"""
1218         uri = uri.replace('#', '/')
1219         if '%' not in uri: return uri
1220         return re.sub('%[0-9a-fA-F][0-9a-fA-F]',
1221                 lambda match: chr(int(match.group(0)[1:], 16)),
1222                 uri).decode('utf-8')
1223
1224 def escape(uri):
1225         """Convert each space to %20, etc
1226         @rtype: str"""
1227         return re.sub('[^-_.a-zA-Z0-9]',
1228                 lambda match: '%%%02x' % ord(match.group(0)),
1229                 uri.encode('utf-8'))
1230
1231 def _pretty_escape(uri):
1232         """Convert each space to %20, etc
1233         : is preserved and / becomes #. This makes for nicer strings,
1234         and may replace L{escape} everywhere in future.
1235         @rtype: str"""
1236         if os.name == "posix":
1237                 # Only preserve : on Posix systems
1238                 preserveRegex = '[^-_.a-zA-Z0-9:/]'
1239         else:
1240                 # Other OSes may not allow the : character in file names
1241                 preserveRegex = '[^-_.a-zA-Z0-9/]'
1242         return re.sub(preserveRegex,
1243                 lambda match: '%%%02x' % ord(match.group(0)),
1244                 uri.encode('utf-8')).replace('/', '#')
1245
1246 def canonical_iface_uri(uri):
1247         """If uri is a relative path, convert to an absolute one.
1248         A "file:///foo" URI is converted to "/foo".
1249         An "alias:prog" URI expands to the URI in the 0alias script
1250         Otherwise, return it unmodified.
1251         @rtype: str
1252         @raise SafeException: if uri isn't valid
1253         """
1254         if uri.startswith('http://') or uri.startswith('https://'):
1255                 if uri.count("/") < 3:
1256                         raise SafeException(_("Missing / after hostname in URI '%s'") % uri)
1257                 return uri
1258         elif uri.startswith('file:///'):
1259                 path = uri[7:]
1260         elif uri.startswith('file:'):
1261                 if uri[5] == '/':
1262                         raise SafeException(_('Use file:///path for absolute paths, not {uri}').format(uri = uri))
1263                 path = os.path.abspath(uri[5:])
1264         elif uri.startswith('alias:'):
1265                 from zeroinstall import alias, support
1266                 alias_prog = uri[6:]
1267                 if not os.path.isabs(alias_prog):
1268                         full_path = support.find_in_path(alias_prog)
1269                         if not full_path:
1270                                 raise alias.NotAnAliasScript("Not found in $PATH: " + alias_prog)
1271                 else:
1272                         full_path = alias_prog
1273                 return alias.parse_script(full_path).uri
1274         else:
1275                 path = os.path.realpath(uri)
1276
1277         if os.path.isfile(path):
1278                 return path
1279         raise SafeException(_("Bad interface name '%(uri)s'.\n"
1280                         "(doesn't start with 'http:', and "
1281                         "doesn't exist as a local file '%(interface_uri)s' either)") %
1282                         {'uri': uri, 'interface_uri': path})
1283
1284 _version_mod_to_value = {
1285         'pre': -2,
1286         'rc': -1,
1287         '': 0,
1288         'post': 1,
1289 }
1290
1291 # Reverse mapping
1292 _version_value_to_mod = {}
1293 for x in _version_mod_to_value: _version_value_to_mod[_version_mod_to_value[x]] = x
1294 del x
1295
1296 _version_re = re.compile('-([a-z]*)')
1297
1298 def parse_version(version_string):
1299         """Convert a version string to an internal representation.
1300         The parsed format can be compared quickly using the standard Python functions.
1301          - Version := DottedList ("-" Mod DottedList?)*
1302          - DottedList := (Integer ("." Integer)*)
1303         @rtype: tuple (opaque)
1304         @raise SafeException: if the string isn't a valid version
1305         @since: 0.24 (moved from L{reader}, from where it is still available):"""
1306         if version_string is None: return None
1307         parts = _version_re.split(version_string)
1308         if parts[-1] == '':
1309                 del parts[-1]   # Ends with a modifier
1310         else:
1311                 parts.append('')
1312         if not parts:
1313                 raise SafeException(_("Empty version string!"))
1314         l = len(parts)
1315         try:
1316                 for x in range(0, l, 2):
1317                         part = parts[x]
1318                         if part:
1319                                 parts[x] = map(int, parts[x].split('.'))
1320                         else:
1321                                 parts[x] = []   # (because ''.split('.') == [''], not [])
1322                 for x in range(1, l, 2):
1323                         parts[x] = _version_mod_to_value[parts[x]]
1324                 return parts
1325         except ValueError as ex:
1326                 raise SafeException(_("Invalid version format in '%(version_string)s': %(exception)s") % {'version_string': version_string, 'exception': ex})
1327         except KeyError as ex:
1328                 raise SafeException(_("Invalid version modifier in '%(version_string)s': %(exception)s") % {'version_string': version_string, 'exception': ex})
1329
1330 def format_version(version):
1331         """Format a parsed version for display. Undoes the effect of L{parse_version}.
1332         @see: L{Implementation.get_version}
1333         @rtype: str
1334         @since: 0.24"""
1335         version = version[:]
1336         l = len(version)
1337         for x in range(0, l, 2):
1338                 version[x] = '.'.join(map(str, version[x]))
1339         for x in range(1, l, 2):
1340                 version[x] = '-' + _version_value_to_mod[version[x]]
1341         if version[-1] == '-': del version[-1]
1342         return ''.join(version)
1343