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 import os, re
  17 from logging import info, debug
  18 from zeroinstall import SafeException, version
  19 from zeroinstall.injector.namespaces import XMLNS_IFACE
  20
  21 # Element names for bindings in feed files
  22 binding_names = frozenset(['environment', 'overlay'])
  23
  24 network_offline = 'off-line'
  25 network_minimal = 'minimal'
  26 network_full = 'full'
  27 network_levels = (network_offline, network_minimal, network_full)
  28
  29 stability_levels = {}   # Name -> Stability
  30
  31 defaults = {
  32         'PATH': '/bin:/usr/bin',
  33         'XDG_CONFIG_DIRS': '/etc/xdg',
  34         'XDG_DATA_DIRS': '/usr/local/share:/usr/share',
  35 }
  36
  37 class InvalidInterface(SafeException):
  38         """Raised when parsing an invalid feed."""
  39         def __init__(self, message, ex = None):
  40                 if ex:
  41                         message += "\n\n(exact error: %s)" % ex
  42                 SafeException.__init__(self, message)
  43
  44 def _split_arch(arch):
  45         """Split an arch into an (os, machine) tuple. Either or both parts may be None."""
  46         if not arch:
  47                 return None, None
  48         elif '-' not in arch:
  49                 raise SafeException("Malformed arch '%s'" % arch)
  50         else:
  51                 osys, machine = arch.split('-', 1)
  52                 if osys == '*': osys = None
  53                 if machine == '*': machine = None
  54                 return osys, machine
  55
  56 def _join_arch(osys, machine):
  57         if osys == machine == None: return None
  58         return "%s-%s" % (osys or '*', machine or '*')
  59
  60 class Stability(object):
  61         """A stability rating. Each implementation has an upstream stability rating and,
  62         optionally, a user-set rating."""
  63         __slots__ = ['level', 'name', 'description']
  64         def __init__(self, level, name, description):
  65                 self.level = level
  66                 self.name = name
  67                 self.description = description
  68                 assert name not in stability_levels
  69                 stability_levels[name] = self
  70
  71         def __cmp__(self, other):
  72                 return cmp(self.level, other.level)
  73
  74         def __str__(self):
  75                 return self.name
  76
  77         def __repr__(self):
  78                 return "<Stability: " + self.description + ">"
  79
  80 def process_binding(e):
  81         """Internal"""
  82         if e.name == 'environment':
  83                 mode = {
  84                         None: EnvironmentBinding.PREPEND,
  85                         'prepend': EnvironmentBinding.PREPEND,
  86                         'append': EnvironmentBinding.APPEND,
  87                         'replace': EnvironmentBinding.REPLACE,
  88                 }[e.getAttribute('mode')]
  89
  90                 binding = EnvironmentBinding(e.getAttribute('name'),
  91                                              insert = e.getAttribute('insert'),
  92                                              default = e.getAttribute('default'),
  93                                              mode = mode)
  94                 if not binding.name: raise InvalidInterface("Missing 'name' in binding")
  95                 if binding.insert is None: raise InvalidInterface("Missing 'insert' in binding")
  96                 return binding
  97         elif e.name == 'overlay':
  98                 return OverlayBinding(e.getAttribute('src'), e.getAttribute('mount-point'))
  99         else:
 100                 raise Exception("Unknown binding type '%s'" % e.name)
 101
 102 def process_depends(item):
 103         """Internal"""
 104         # Note: also called from selections
 105         dep_iface = item.getAttribute('interface')
 106         if not dep_iface:
 107                 raise InvalidInterface("Missing 'interface' on <requires>")
 108         dependency = InterfaceDependency(dep_iface, metadata = item.attrs)
 109
 110         for e in item.childNodes:
 111                 if e.uri != XMLNS_IFACE: continue
 112                 if e.name in binding_names:
 113                         dependency.bindings.append(process_binding(e))
 114                 elif e.name == 'version':
 115                         dependency.restrictions.append(
 116                                 VersionRangeRestriction(not_before = parse_version(e.getAttribute('not-before')),
 117                                                         before = parse_version(e.getAttribute('before'))))
 118         return dependency
 119
 120
 121 insecure = Stability(0, 'insecure', 'This is a security risk')
 122 buggy = Stability(5, 'buggy', 'Known to have serious bugs')
 123 developer = Stability(10, 'developer', 'Work-in-progress - bugs likely')
 124 testing = Stability(20, 'testing', 'Stability unknown - please test!')
 125 stable = Stability(30, 'stable', 'Tested - no serious problems found')
 126 packaged = Stability(35, 'packaged', 'Supplied by the local package manager')
 127 preferred = Stability(40, 'preferred', 'Best of all - must be set manually')
 128
 129 class Restriction(object):
 130         """A Restriction limits the allowed implementations of an Interface."""
 131         __slots__ = []
 132
 133         def meets_restriction(self, impl):
 134                 """Called by the L{Solver} to check whether a particular implementation is acceptable.
 135                 @return: False if this implementation is not a possibility
 136                 @rtype: bool
 137                 """
 138                 raise NotImplementedError("Abstract")
 139
 140 class VersionRestriction(Restriction):
 141         """Only select implementations with a particular version number.
 142         @since: 0.40"""
 143
 144         def __init__(self, version):
 145                 """@param version: the required version number
 146                 @see: L{parse_version}; use this to pre-process the version number
 147                 """
 148                 self.version = version
 149
 150         def meets_restriction(self, impl):
 151                 return impl.version == self.version
 152
 153         def __str__(self):
 154                 return "(restriction: version = %s)" % format_version(self.version)
 155
 156 class VersionRangeRestriction(Restriction):
 157         """Only versions within the given range are acceptable"""
 158         __slots__ = ['before', 'not_before']
 159
 160         def __init__(self, before, not_before):
 161                 """@param before: chosen versions must be earlier than this
 162                 @param not_before: versions must be at least this high
 163                 @see: L{parse_version}; use this to pre-process the versions
 164                 """
 165                 self.before = before
 166                 self.not_before = not_before
 167
 168         def meets_restriction(self, impl):
 169                 if self.not_before and impl.version < self.not_before:
 170                         return False
 171                 if self.before and impl.version >= self.before:
 172                         return False
 173                 return True
 174
 175         def __str__(self):
 176                 if self.not_before is not None or self.before is not None:
 177                         range = ''
 178                         if self.not_before is not None:
 179                                 range += format_version(self.not_before) + ' <= '
 180                         range += 'version'
 181                         if self.before is not None:
 182                                 range += ' < ' + format_version(self.before)
 183                 else:
 184                         range = 'none'
 185                 return "(restriction: %s)" % range
 186
 187 class Binding(object):
 188         """Information about how the choice of a Dependency is made known
 189         to the application being run."""
 190
 191 class EnvironmentBinding(Binding):
 192         """Indicate the chosen implementation using an environment variable."""
 193         __slots__ = ['name', 'insert', 'default', 'mode']
 194
 195         PREPEND = 'prepend'
 196         APPEND = 'append'
 197         REPLACE = 'replace'
 198
 199         def __init__(self, name, insert, default = None, mode = PREPEND):
 200                 """mode argument added in version 0.28"""
 201                 self.name = name
 202                 self.insert = insert
 203                 self.default = default
 204                 self.mode = mode
 205
 206         def __str__(self):
 207                 return "<environ %s %s %s>" % (self.name, self.mode, self.insert)
 208
 209         __repr__ = __str__
 210
 211         def get_value(self, path, old_value):
 212                 """Calculate the new value of the environment variable after applying this binding.
 213                 @param path: the path to the selected implementation
 214                 @param old_value: the current value of the environment variable
 215                 @return: the new value for the environment variable"""
 216                 extra = os.path.join(path, self.insert)
 217
 218                 if self.mode == EnvironmentBinding.REPLACE:
 219                         return extra
 220
 221                 if old_value is None:
 222                         old_value = self.default or defaults.get(self.name, None)
 223                 if old_value is None:
 224                         return extra
 225                 if self.mode == EnvironmentBinding.PREPEND:
 226                         return extra + ':' + old_value
 227                 else:
 228                         return old_value + ':' + extra
 229
 230         def _toxml(self, doc):
 231                 """Create a DOM element for this binding.
 232                 @param doc: document to use to create the element
 233                 @return: the new element
 234                 """
 235                 env_elem = doc.createElementNS(XMLNS_IFACE, 'environment')
 236                 env_elem.setAttributeNS(None, 'name', self.name)
 237                 env_elem.setAttributeNS(None, 'insert', self.insert)
 238                 if self.default:
 239                         env_elem.setAttributeNS(None, 'default', self.default)
 240                 return env_elem
 241
 242 class OverlayBinding(Binding):
 243         """Make the chosen implementation available by overlaying it onto another part of the file-system.
 244         This is to support legacy programs which use hard-coded paths."""
 245         __slots__ = ['src', 'mount_point']
 246
 247         def __init__(self, src, mount_point):
 248                 self.src = src
 249                 self.mount_point = mount_point
 250
 251         def __str__(self):
 252                 return "<overlay %s on %s>" % (self.src or '.', self.mount_point or '/')
 253
 254         __repr__ = __str__
 255
 256         def _toxml(self, doc):
 257                 """Create a DOM element for this binding.
 258                 @param doc: document to use to create the element
 259                 @return: the new element
 260                 """
 261                 env_elem = doc.createElementNS(XMLNS_IFACE, 'overlay')
 262                 if self.src is not None:
 263                         env_elem.setAttributeNS(None, 'src', self.src)
 264                 if self.mount_point is not None:
 265                         env_elem.setAttributeNS(None, 'mount-point', self.mount_point)
 266                 return env_elem
 267
 268 class Feed(object):
 269         """An interface's feeds are other interfaces whose implementations can also be
 270         used as implementations of this interface."""
 271         __slots__ = ['uri', 'os', 'machine', 'user_override', 'langs']
 272         def __init__(self, uri, arch, user_override, langs = None):
 273                 self.uri = uri
 274                 # This indicates whether the feed comes from the user's overrides
 275                 # file. If true, writer.py will write it when saving.
 276                 self.user_override = user_override
 277                 self.os, self.machine = _split_arch(arch)
 278                 self.langs = langs
 279
 280         def __str__(self):
 281                 return "<Feed from %s>" % self.uri
 282         __repr__ = __str__
 283
 284         arch = property(lambda self: _join_arch(self.os, self.machine))
 285
 286 class Dependency(object):
 287         """A Dependency indicates that an Implementation requires some additional
 288         code to function. This is an abstract base class.
 289         @ivar metadata: any extra attributes from the XML element
 290         @type metadata: {str: str}
 291         """
 292         __slots__ = ['metadata']
 293
 294         def __init__(self, metadata):
 295                 if metadata is None:
 296                         metadata = {}
 297                 else:
 298                         assert not isinstance(metadata, basestring)     # Use InterfaceDependency instead!
 299                 self.metadata = metadata
 300
 301 class InterfaceDependency(Dependency):
 302         """A Dependency on a Zero Install interface.
 303         @ivar interface: the interface required by this dependency
 304         @type interface: str
 305         @ivar restrictions: a list of constraints on acceptable implementations
 306         @type restrictions: [L{Restriction}]
 307         @ivar bindings: how to make the choice of implementation known
 308         @type bindings: [L{Binding}]
 309         @since: 0.28
 310         """
 311         __slots__ = ['interface', 'restrictions', 'bindings', 'metadata']
 312
 313         def __init__(self, interface, restrictions = None, metadata = None):
 314                 Dependency.__init__(self, metadata)
 315                 assert isinstance(interface, (str, unicode))
 316                 assert interface
 317                 self.interface = interface
 318                 if restrictions is None:
 319                         self.restrictions = []
 320                 else:
 321                         self.restrictions = restrictions
 322                 self.bindings = []
 323
 324         def __str__(self):
 325                 return "<Dependency on %s; bindings: %s%s>" % (self.interface, self.bindings, self.restrictions)
 326
 327 class RetrievalMethod(object):
 328         """A RetrievalMethod provides a way to fetch an implementation."""
 329         __slots__ = []
 330
 331 class DownloadSource(RetrievalMethod):
 332         """A DownloadSource provides a way to fetch an implementation."""
 333         __slots__ = ['implementation', 'url', 'size', 'extract', 'start_offset', 'type']
 334
 335         def __init__(self, implementation, url, size, extract, start_offset = 0, type = None):
 336                 self.implementation = implementation
 337                 self.url = url
 338                 self.size = size
 339                 self.extract = extract
 340                 self.start_offset = start_offset
 341                 self.type = type                # MIME type - see unpack.py
 342
 343 class Recipe(RetrievalMethod):
 344         """Get an implementation by following a series of steps.
 345         @ivar size: the combined download sizes from all the steps
 346         @type size: int
 347         @ivar steps: the sequence of steps which must be performed
 348         @type steps: [L{RetrievalMethod}]"""
 349         __slots__ = ['steps']
 350
 351         def __init__(self):
 352                 self.steps = []
 353
 354         size = property(lambda self: sum([x.size for x in self.steps]))
 355
 356 class Implementation(object):
 357         """An Implementation is a package which implements an Interface.
 358         @ivar download_sources: list of methods of getting this implementation
 359         @type download_sources: [L{RetrievalMethod}]
 360         @ivar feed: the feed owning this implementation (since 0.32)
 361         @type feed: [L{ZeroInstallFeed}]
 362         @ivar bindings: how to tell this component where it itself is located (since 0.31)
 363         @type bindings: [Binding]
 364         @ivar upstream_stability: the stability reported by the packager
 365         @type upstream_stability: [insecure | buggy | developer | testing | stable | packaged]
 366         @ivar user_stability: the stability as set by the user
 367         @type upstream_stability: [insecure | buggy | developer | testing | stable | packaged | preferred]
 368         @ivar langs: natural languages supported by this package
 369         @ivar requires: interfaces this package depends on
 370         @ivar main: the default file to execute when running as a program
 371         @ivar metadata: extra metadata from the feed
 372         @type metadata: {"[URI ]localName": str}
 373         @ivar id: a unique identifier for this Implementation
 374         @ivar version: a parsed version number
 375         @ivar released: release date
 376         """
 377
 378         # Note: user_stability shouldn't really be here
 379
 380         __slots__ = ['upstream_stability', 'user_stability', 'langs',
 381                      'requires', 'main', 'metadata', 'download_sources',
 382                      'id', 'feed', 'version', 'released', 'bindings', 'machine']
 383
 384         def __init__(self, feed, id):
 385                 assert id
 386                 self.feed = feed
 387                 self.id = id
 388                 self.main = None
 389                 self.user_stability = None
 390                 self.upstream_stability = None
 391                 self.metadata = {}      # [URI + " "] + localName -> value
 392                 self.requires = []
 393                 self.version = None
 394                 self.released = None
 395                 self.download_sources = []
 396                 self.langs = None
 397                 self.machine = None
 398                 self.bindings = []
 399
 400         def get_stability(self):
 401                 return self.user_stability or self.upstream_stability or testing
 402
 403         def __str__(self):
 404                 return self.id
 405
 406         def __repr__(self):
 407                 return "v%s (%s)" % (self.get_version(), self.id)
 408
 409         def __cmp__(self, other):
 410                 """Newer versions come first"""
 411                 return cmp(other.version, self.version)
 412
 413         def get_version(self):
 414                 """Return the version as a string.
 415                 @see: L{format_version}
 416                 """
 417                 return format_version(self.version)
 418
 419         arch = property(lambda self: _join_arch(self.os, self.machine))
 420
 421         os = None
 422
 423 class DistributionImplementation(Implementation):
 424         """An implementation provided by the distribution. Information such as the version
 425         comes from the package manager.
 426         @since: 0.28"""
 427         __slots__ = ['installed']
 428
 429         def __init__(self, feed, id):
 430                 assert id.startswith('package:')
 431                 Implementation.__init__(self, feed, id)
 432                 self.installed = True
 433
 434 class ZeroInstallImplementation(Implementation):
 435         """An implementation where all the information comes from Zero Install.
 436         @since: 0.28"""
 437         __slots__ = ['os', 'size']
 438
 439         def __init__(self, feed, id):
 440                 """id can be a local path (string starting with /) or a manifest hash (eg "sha1=XXX")"""
 441                 Implementation.__init__(self, feed, id)
 442                 self.size = None
 443                 self.os = None
 444
 445         # Deprecated
 446         dependencies = property(lambda self: dict([(x.interface, x) for x in self.requires
 447                                                    if isinstance(x, InterfaceDependency)]))
 448
 449         def add_download_source(self, url, size, extract, start_offset = 0, type = None):
 450                 """Add a download source."""
 451                 self.download_sources.append(DownloadSource(self, url, size, extract, start_offset, type))
 452
 453         def set_arch(self, arch):
 454                 self.os, self.machine = _split_arch(arch)
 455         arch = property(lambda self: _join_arch(self.os, self.machine), set_arch)
 456
 457 class Interface(object):
 458         """An Interface represents some contract of behaviour.
 459         @ivar uri: the URI for this interface.
 460         @ivar stability_policy: user's configured policy.
 461         Implementations at this level or higher are preferred.
 462         Lower levels are used only if there is no other choice.
 463         """
 464         __slots__ = ['uri', 'stability_policy', '_main_feed', 'extra_feeds']
 465
 466         implementations = property(lambda self: self._main_feed.implementations)
 467         name = property(lambda self: self._main_feed.name)
 468         description = property(lambda self: self._main_feed.description)
 469         summary = property(lambda self: self._main_feed.summary)
 470         last_modified = property(lambda self: self._main_feed.last_modified)
 471         feeds = property(lambda self: self.extra_feeds + self._main_feed.feeds)
 472         metadata = property(lambda self: self._main_feed.metadata)
 473
 474         last_checked = property(lambda self: self._main_feed.last_checked)
 475
 476         def __init__(self, uri):
 477                 assert uri
 478                 if uri.startswith('http:') or uri.startswith('/'):
 479                         self.uri = uri
 480                 else:
 481                         raise SafeException("Interface name '%s' doesn't start "
 482                                             "with 'http:'" % uri)
 483                 self.reset()
 484
 485         def _get_feed_for(self):
 486                 retval = {}
 487                 for key in self._main_feed.feed_for:
 488                         retval[key] = True
 489                 return retval
 490         feed_for = property(_get_feed_for)      # Deprecated (used by 0publish)
 491
 492         def reset(self):
 493                 self.extra_feeds = []
 494                 self._main_feed = _dummy_feed
 495                 self.stability_policy = None
 496
 497         def get_name(self):
 498                 if self._main_feed is not _dummy_feed:
 499                         return self._main_feed.get_name()
 500                 return '(' + os.path.basename(self.uri) + ')'
 501
 502         def __repr__(self):
 503                 return "<Interface %s>" % self.uri
 504
 505         def set_stability_policy(self, new):
 506                 assert new is None or isinstance(new, Stability)
 507                 self.stability_policy = new
 508
 509         def get_feed(self, url):
 510                 for x in self.extra_feeds:
 511                         if x.uri == url:
 512                                 return x
 513                 return self._main_feed.get_feed(url)
 514
 515         def get_metadata(self, uri, name):
 516                 return self._main_feed.get_metadata(uri, name)
 517
 518 def _merge_attrs(attrs, item):
 519         """Add each attribute of item to a copy of attrs and return the copy.
 520         @type attrs: {str: str}
 521         @type item: L{qdom.Element}
 522         @rtype: {str: str}
 523         """
 524         new = attrs.copy()
 525         for a in item.attrs:
 526                 new[str(a)] = item.attrs[a]
 527         return new
 528
 529 def _get_long(elem, attr_name):
 530         val = elem.getAttribute(attr_name)
 531         if val is not None:
 532                 try:
 533                         val = long(val)
 534                 except ValueError, ex:
 535                         raise SafeException("Invalid value for integer attribute '%s': %s" % (attr_name, val))
 536         return val
 537
 538 class ZeroInstallFeed(object):
 539         """A feed lists available implementations of an interface.
 540         @ivar url: the URL for this feed
 541         @ivar implementations: Implementations in this feed, indexed by ID
 542         @type implementations: {str: L{Implementation}}
 543         @ivar name: human-friendly name
 544         @ivar summary: short textual description
 545         @ivar description: long textual description
 546         @ivar last_modified: timestamp on signature
 547         @ivar last_checked: time feed was last successfully downloaded and updated
 548         @ivar feeds: list of <feed> elements in this feed
 549         @type feeds: [L{Feed}]
 550         @ivar feed_for: interfaces for which this could be a feed
 551         @type feed_for: set(str)
 552         @ivar metadata: extra elements we didn't understand
 553         """
 554         # _main is deprecated
 555         __slots__ = ['url', 'implementations', 'name', 'description', 'summary',
 556                      'last_checked', 'last_modified', 'feeds', 'feed_for', 'metadata']
 557
 558         def __init__(self, feed_element, local_path = None, distro = None):
 559                 """Create a feed object from a DOM.
 560                 @param feed_element: the root element of a feed file
 561                 @type feed_element: L{qdom.Element}
 562                 @param local_path: the pathname of this local feed, or None for remote feeds
 563                 @param distro: used to resolve distribution package references
 564                 @type distro: L{distro.Distribution} or None"""
 565                 assert feed_element
 566                 self.implementations = {}
 567                 self.name = None
 568                 self.summary = None
 569                 self.description = ""
 570                 self.last_modified = None
 571                 self.feeds = []
 572                 self.feed_for = set()
 573                 self.metadata = []
 574                 self.last_checked = None
 575
 576                 assert feed_element.name in ('interface', 'feed'), "Root element should be <interface>, not %s" % feed_element
 577                 assert feed_element.uri == XMLNS_IFACE, "Wrong namespace on root element: %s" % feed_element.uri
 578
 579                 main = feed_element.getAttribute('main')
 580                 #if main: warn("Setting 'main' on the root element is deprecated. Put it on a <group> instead")
 581
 582                 if local_path:
 583                         self.url = local_path
 584                         local_dir = os.path.dirname(local_path)
 585                 else:
 586                         self.url = feed_element.getAttribute('uri')
 587                         if not self.url:
 588                                 raise InvalidInterface("<interface> uri attribute missing")
 589                         local_dir = None        # Can't have relative paths
 590
 591                 min_injector_version = feed_element.getAttribute('min-injector-version')
 592                 if min_injector_version:
 593                         if parse_version(min_injector_version) > parse_version(version):
 594                                 raise InvalidInterface("This feed requires version %s or later of "
 595                                                         "Zero Install, but I am only version %s. "
 596                                                         "You can get a newer version from http://0install.net" %
 597                                                         (min_injector_version, version))
 598
 599                 for x in feed_element.childNodes:
 600                         if x.uri != XMLNS_IFACE:
 601                                 self.metadata.append(x)
 602                                 continue
 603                         if x.name == 'name':
 604                                 self.name = x.content
 605                         elif x.name == 'description':
 606                                 self.description = x.content
 607                         elif x.name == 'summary':
 608                                 self.summary = x.content
 609                         elif x.name == 'feed-for':
 610                                 feed_iface = x.getAttribute('interface')
 611                                 if not feed_iface:
 612                                         raise InvalidInterface('Missing "interface" attribute in <feed-for>')
 613                                 self.feed_for.add(feed_iface)
 614                                 # Bug report from a Debian/stable user that --feed gets the wrong value.
 615                                 # Can't reproduce (even in a Debian/stable chroot), but add some logging here
 616                                 # in case it happens again.
 617                                 debug("Is feed-for %s", feed_iface)
 618                         elif x.name == 'feed':
 619                                 feed_src = x.getAttribute('src')
 620                                 if not feed_src:
 621                                         raise InvalidInterface('Missing "src" attribute in <feed>')
 622                                 if feed_src.startswith('http:') or local_path:
 623                                         self.feeds.append(Feed(feed_src, x.getAttribute('arch'), False, langs = x.getAttribute('langs')))
 624                                 else:
 625                                         raise InvalidInterface("Invalid feed URL '%s'" % feed_src)
 626                         else:
 627                                 self.metadata.append(x)
 628
 629                 if not self.name:
 630                         raise InvalidInterface("Missing <name> in feed")
 631                 if not self.summary:
 632                         raise InvalidInterface("Missing <summary> in feed")
 633
 634                 def process_group(group, group_attrs, base_depends, base_bindings):
 635                         for item in group.childNodes:
 636                                 if item.uri != XMLNS_IFACE: continue
 637
 638                                 if item.name not in ('group', 'implementation', 'package-implementation'):
 639                                         continue
 640
 641                                 depends = base_depends[:]
 642                                 bindings = base_bindings[:]
 643
 644                                 item_attrs = _merge_attrs(group_attrs, item)
 645
 646                                 # We've found a group or implementation. Scan for dependencies
 647                                 # and bindings. Doing this here means that:
 648                                 # - We can share the code for groups and implementations here.
 649                                 # - The order doesn't matter, because these get processed first.
 650                                 # A side-effect is that the document root cannot contain
 651                                 # these.
 652                                 for child in item.childNodes:
 653                                         if child.uri != XMLNS_IFACE: continue
 654                                         if child.name == 'requires':
 655                                                 dep = process_depends(child)
 656                                                 depends.append(dep)
 657                                         elif child.name in binding_names:
 658                                                 bindings.append(process_binding(child))
 659
 660                                 if item.name == 'group':
 661                                         process_group(item, item_attrs, depends, bindings)
 662                                 elif item.name == 'implementation':
 663                                         process_impl(item, item_attrs, depends, bindings)
 664                                 elif item.name == 'package-implementation':
 665                                         process_native_impl(item, item_attrs, depends)
 666                                 else:
 667                                         assert 0
 668
 669                 def process_impl(item, item_attrs, depends, bindings):
 670                         id = item.getAttribute('id')
 671                         if id is None:
 672                                 raise InvalidInterface("Missing 'id' attribute on %s" % item)
 673                         if local_dir and (id.startswith('/') or id.startswith('.')):
 674                                 impl = self._get_impl(os.path.abspath(os.path.join(local_dir, id)))
 675                         else:
 676                                 if '=' not in id:
 677                                         raise InvalidInterface('Invalid "id"; form is "alg=value" (got "%s")' % id)
 678                                 alg, sha1 = id.split('=')
 679                                 try:
 680                                         long(sha1, 16)
 681                                 except Exception, ex:
 682                                         raise InvalidInterface('Bad SHA1 attribute: %s' % ex)
 683                                 impl = self._get_impl(id)
 684
 685                         impl.metadata = item_attrs
 686                         try:
 687                                 version_mod = item_attrs.get('version-modifier', None)
 688                                 if version_mod:
 689                                         item_attrs['version'] += version_mod
 690                                         del item_attrs['version-modifier']
 691                                 version = item_attrs['version']
 692                         except KeyError:
 693                                 raise InvalidInterface("Missing version attribute")
 694                         impl.version = parse_version(version)
 695
 696                         item_main = item_attrs.get('main', None)
 697                         if item_main and item_main.startswith('/'):
 698                                 raise InvalidInterface("'main' attribute must be relative, but '%s' starts with '/'!" %
 699                                                         item_main)
 700                         impl.main = item_main
 701
 702                         impl.released = item_attrs.get('released', None)
 703                         impl.langs = item_attrs.get('langs', None)
 704
 705                         size = item.getAttribute('size')
 706                         if size:
 707                                 impl.size = long(size)
 708                         impl.arch = item_attrs.get('arch', None)
 709                         try:
 710                                 stability = stability_levels[str(item_attrs['stability'])]
 711                         except KeyError:
 712                                 stab = str(item_attrs['stability'])
 713                                 if stab != stab.lower():
 714                                         raise InvalidInterface('Stability "%s" invalid - use lower case!' % item_attrs.stability)
 715                                 raise InvalidInterface('Stability "%s" invalid' % item_attrs['stability'])
 716                         if stability >= preferred:
 717                                 raise InvalidInterface("Upstream can't set stability to preferred!")
 718                         impl.upstream_stability = stability
 719
 720                         impl.bindings = bindings
 721                         impl.requires = depends
 722
 723                         for elem in item.childNodes:
 724                                 if elem.uri != XMLNS_IFACE: continue
 725                                 if elem.name == 'archive':
 726                                         url = elem.getAttribute('href')
 727                                         if not url:
 728                                                 raise InvalidInterface("Missing href attribute on <archive>")
 729                                         size = elem.getAttribute('size')
 730                                         if not size:
 731                                                 raise InvalidInterface("Missing size attribute on <archive>")
 732                                         impl.add_download_source(url = url, size = long(size),
 733                                                         extract = elem.getAttribute('extract'),
 734                                                         start_offset = _get_long(elem, 'start-offset'),
 735                                                         type = elem.getAttribute('type'))
 736                                 elif elem.name == 'recipe':
 737                                         recipe = Recipe()
 738                                         for recipe_step in elem.childNodes:
 739                                                 if recipe_step.uri == XMLNS_IFACE and recipe_step.name == 'archive':
 740                                                         url = recipe_step.getAttribute('href')
 741                                                         if not url:
 742                                                                 raise InvalidInterface("Missing href attribute on <archive>")
 743                                                         size = recipe_step.getAttribute('size')
 744                                                         if not size:
 745                                                                 raise InvalidInterface("Missing size attribute on <archive>")
 746                                                         recipe.steps.append(DownloadSource(None, url = url, size = long(size),
 747                                                                         extract = recipe_step.getAttribute('extract'),
 748                                                                         start_offset = _get_long(recipe_step, 'start-offset'),
 749                                                                         type = recipe_step.getAttribute('type')))
 750                                                 else:
 751                                                         info("Unknown step '%s' in recipe; skipping recipe", recipe_step.name)
 752                                                         break
 753                                         else:
 754                                                 impl.download_sources.append(recipe)
 755
 756                 def process_native_impl(item, item_attrs, depends):
 757                         package = item_attrs.get('package', None)
 758                         if package is None:
 759                                 raise InvalidInterface("Missing 'package' attribute on %s" % item)
 760
 761                         def factory(id):
 762                                 assert id.startswith('package:')
 763                                 impl = self._get_impl(id)
 764
 765                                 impl.metadata = item_attrs
 766
 767                                 item_main = item_attrs.get('main', None)
 768                                 if item_main and not item_main.startswith('/'):
 769                                         raise InvalidInterface("'main' attribute must be absolute, but '%s' doesn't start with '/'!" %
 770                                                                 item_main)
 771                                 impl.main = item_main
 772                                 impl.upstream_stability = packaged
 773                                 impl.requires = depends
 774
 775                                 return impl
 776
 777                         distro.get_package_info(package, factory)
 778
 779                 root_attrs = {'stability': 'testing'}
 780                 if main:
 781                         root_attrs['main'] = main
 782                 process_group(feed_element, root_attrs, [], [])
 783
 784         def get_name(self):
 785                 return self.name or '(' + os.path.basename(self.url) + ')'
 786
 787         def __repr__(self):
 788                 return "<Feed %s>" % self.url
 789
 790         def _get_impl(self, id):
 791                 if id not in self.implementations:
 792                         if id.startswith('package:'):
 793                                 impl = DistributionImplementation(self, id)
 794                         else:
 795                                 impl = ZeroInstallImplementation(self, id)
 796                         self.implementations[id] = impl
 797                 return self.implementations[id]
 798
 799         def set_stability_policy(self, new):
 800                 assert new is None or isinstance(new, Stability)
 801                 self.stability_policy = new
 802
 803         def get_feed(self, url):
 804                 for x in self.feeds:
 805                         if x.uri == url:
 806                                 return x
 807                 return None
 808
 809         def add_metadata(self, elem):
 810                 self.metadata.append(elem)
 811
 812         def get_metadata(self, uri, name):
 813                 """Return a list of interface metadata elements with this name and namespace URI."""
 814                 return [m for m in self.metadata if m.name == name and m.uri == uri]
 815
 816 class DummyFeed(object):
 817         """Temporary class used during API transition."""
 818         last_modified = None
 819         name = '-'
 820         last_checked = property(lambda self: None)
 821         implementations = property(lambda self: {})
 822         feeds = property(lambda self: [])
 823         summary = property(lambda self: '-')
 824         description = property(lambda self: '')
 825         def get_name(self): return self.name
 826         def get_feed(self, url): return None
 827         def get_metadata(self, uri, name): return []
 828 _dummy_feed = DummyFeed()
 829
 830 def unescape(uri):
 831         """Convert each %20 to a space, etc.
 832         @rtype: str"""
 833         uri = uri.replace('#', '/')
 834         if '%' not in uri: return uri
 835         return re.sub('%[0-9a-fA-F][0-9a-fA-F]',
 836                 lambda match: chr(int(match.group(0)[1:], 16)),
 837                 uri).decode('utf-8')
 838
 839 def escape(uri):
 840         """Convert each space to %20, etc
 841         @rtype: str"""
 842         return re.sub('[^-_.a-zA-Z0-9]',
 843                 lambda match: '%%%02x' % ord(match.group(0)),
 844                 uri.encode('utf-8'))
 845
 846 def _pretty_escape(uri):
 847         """Convert each space to %20, etc
 848         : is preserved and / becomes #. This makes for nicer strings,
 849         and may replace L{escape} everywhere in future.
 850         @rtype: str"""
 851         return re.sub('[^-_.a-zA-Z0-9:/]',
 852                 lambda match: '%%%02x' % ord(match.group(0)),
 853                 uri.encode('utf-8')).replace('/', '#')
 854
 855 def canonical_iface_uri(uri):
 856         """If uri is a relative path, convert to an absolute one.
 857         A "file:///foo" URI is converted to "/foo".
 858         Otherwise, return it unmodified.
 859         @rtype: str
 860         @raise SafeException: if uri isn't valid
 861         """
 862         if uri.startswith('http://'):
 863                 if uri.find("/", 7) == -1:
 864                         raise SafeException("Missing / after hostname in URI '%s'" % uri)
 865                 return uri
 866         elif uri.startswith('file:///'):
 867                 return uri[7:]
 868         else:
 869                 iface_uri = os.path.realpath(uri)
 870                 if os.path.isfile(iface_uri):
 871                         return iface_uri
 872         raise SafeException("Bad interface name '%s'.\n"
 873                         "(doesn't start with 'http:', and "
 874                         "doesn't exist as a local file '%s' either)" %
 875                         (uri, iface_uri))
 876
 877 _version_mod_to_value = {
 878         'pre': -2,
 879         'rc': -1,
 880         '': 0,
 881         'post': 1,
 882 }
 883
 884 # Reverse mapping
 885 _version_value_to_mod = {}
 886 for x in _version_mod_to_value: _version_value_to_mod[_version_mod_to_value[x]] = x
 887 del x
 888
 889 _version_re = re.compile('-([a-z]*)')
 890
 891 def parse_version(version_string):
 892         """Convert a version string to an internal representation.
 893         The parsed format can be compared quickly using the standard Python functions.
 894          - Version := DottedList ("-" Mod DottedList?)*
 895          - DottedList := (Integer ("." Integer)*)
 896         @rtype: tuple (opaque)
 897         @raise SafeException: if the string isn't a valid version
 898         @since: 0.24 (moved from L{reader}, from where it is still available):"""
 899         if version_string is None: return None
 900         parts = _version_re.split(version_string)
 901         if parts[-1] == '':
 902                 del parts[-1]   # Ends with a modifier
 903         else:
 904                 parts.append('')
 905         if not parts:
 906                 raise SafeException("Empty version string!")
 907         l = len(parts)
 908         try:
 909                 for x in range(0, l, 2):
 910                         part = parts[x]
 911                         if part:
 912                                 parts[x] = map(int, parts[x].split('.'))
 913                         else:
 914                                 parts[x] = []   # (because ''.split('.') == [''], not [])
 915                 for x in range(1, l, 2):
 916                         parts[x] = _version_mod_to_value[parts[x]]
 917                 return parts
 918         except ValueError, ex:
 919                 raise SafeException("Invalid version format in '%s': %s" % (version_string, ex))
 920         except KeyError, ex:
 921                 raise SafeException("Invalid version modifier in '%s': %s" % (version_string, ex))
 922
 923 def format_version(version):
 924         """Format a parsed version for display. Undoes the effect of L{parse_version}.
 925         @see: L{Implementation.get_version}
 926         @rtype: str
 927         @since: 0.24"""
 928         version = version[:]
 929         l = len(version)
 930         for x in range(0, l, 2):
 931                 version[x] = '.'.join(map(str, version[x]))
 932         for x in range(1, l, 2):
 933                 version[x] = '-' + _version_value_to_mod[version[x]]
 934         if version[-1] == '-': del version[-1]
 935         return ''.join(version)
 936