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