zeroinstall/injector/model.py

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