This is an archive of the discontinued Mercurial Phabricator instance.

Differential D3869

repository: define manifest interfaces
ClosedPublic

Authored by indygreg on Jun 30 2018, 9:35 PM.

Details

Reviewers
durin42
Group Reviewers
hg-reviewers
Commits
rHGc82ea938efbb: repository: define manifest interfaces
Summary

The long march towards declaring interfaces for repository
primitives continues.

This commit essentially defines interfaces based on the following
types:

  • manifest.manifestdict -> imanifestdict
  • manifest.manifestlog -> imanifestlog
  • manifest.memmanifestctx -> imanifestrevisionwritable
  • manifest.manifestctx -> imanifestrevisionstored
  • manifest.memtreemanifestctx -> imanifestrevisionwritable
  • manifest.treemanifestctx -> imanifestrevisionstored
  • util.dirs -> idirs

The interfaces are thoroughly documented. Their documentation is
now better than the documentation in manifest.py in many cases.

With the exception of util.dirs, classes have been annotated with
their interfaces. (I didn't feel like util.dirs needed the
proper interface treatment.)

Tests have been added demonstrating that all classes and instances
conform to their interfaces.

This work was much easier than filelogs. That's because Durham
did an excellent job formalizing the manifest API a while back.

There are still some minor kludges with the interfaces that should
probably be addressed. But the primary goal with interface
declarations is getting something established. Once we have an
interface, we can modify it later easily enough.

Diff Detail

Repository
rHG Mercurial
Lint
Automatic diff as part of commit; lint not applicable.
Unit
Automatic diff as part of commit; unit tests not applicable.

Event Timeline

indygreg created this revision.Jun 30 2018, 9:35 PM
durin42 accepted this revision.Jul 3 2018, 1:40 PM
This revision is now accepted and ready to land.Jul 3 2018, 1:40 PM
Closed by commit rHGc82ea938efbb: repository: define manifest interfaces (authored by indygreg). · Explain WhyJul 3 2018, 1:56 PM
This revision was automatically updated to reflect the committed changes.

Revision Contents
Changeset List

Diff 9415

mercurial/manifest.py

bin, bin,
hex, hex,
) )
from . import ( from . import (
error, error,
mdiff, mdiff,
policy, policy,
pycompat, pycompat,
repository,
revlog, revlog,
util, util,
) )
from .utils import (
interfaceutil,
)
parsers = policy.importmod(r'parsers') parsers = policy.importmod(r'parsers')
propertycache = util.propertycache propertycache = util.propertycache
def _parse(data): def _parse(data):
# This method does a little bit of excessive-looking # This method does a little bit of excessive-looking
# precondition checking. This is so that the behavior of this # precondition checking. This is so that the behavior of this
# class exactly matches its C counterpart to try and help # class exactly matches its C counterpart to try and help
c[f] = n, fl c[f] = n, fl
return c return c
try: try:
_lazymanifest = parsers.lazymanifest _lazymanifest = parsers.lazymanifest
except AttributeError: except AttributeError:
pass pass
@interfaceutil.implementer(repository.imanifestdict)
class manifestdict(object): class manifestdict(object):
def __init__(self, data=''): def __init__(self, data=''):
self._lm = _lazymanifest(data) self._lm = _lazymanifest(data)
def __getitem__(self, key): def __getitem__(self, key):
return self._lm[key][0] return self._lm[key][0]
def find(self, key): def find(self, key):
if not n: if not n:
n = self.addrevision(text, transaction, link, m1.node(), m2.node()) n = self.addrevision(text, transaction, link, m1.node(), m2.node())
# Save nodeid so parent manifest can calculate its nodeid # Save nodeid so parent manifest can calculate its nodeid
m.setnode(n) m.setnode(n)
return n return n
@interfaceutil.implementer(repository.imanifestlog)
class manifestlog(object): class manifestlog(object):
"""A collection class representing the collection of manifest snapshots """A collection class representing the collection of manifest snapshots
referenced by commits in the repository. referenced by commits in the repository.
In this situation, 'manifest' refers to the abstract concept of a snapshot In this situation, 'manifest' refers to the abstract concept of a snapshot
of the list of files in the given commit. Consumers of the output of this of the list of files in the given commit. Consumers of the output of this
class do not care about the implementation details of the actual manifests class do not care about the implementation details of the actual manifests
they receive (i.e. tree or flat or lazily loaded, etc).""" they receive (i.e. tree or flat or lazily loaded, etc)."""
self._dirmancache[dir] = mancache self._dirmancache[dir] = mancache
mancache[node] = m mancache[node] = m
return m return m
def clearcaches(self): def clearcaches(self):
self._dirmancache.clear() self._dirmancache.clear()
self._revlog.clearcaches() self._revlog.clearcaches()
@interfaceutil.implementer(repository.imanifestrevisionwritable)
class memmanifestctx(object): class memmanifestctx(object):
def __init__(self, manifestlog): def __init__(self, manifestlog):
self._manifestlog = manifestlog self._manifestlog = manifestlog
self._manifestdict = manifestdict() self._manifestdict = manifestdict()
def _revlog(self): def _revlog(self):
return self._manifestlog._revlog return self._manifestlog._revlog
def new(self): def new(self):
return memmanifestctx(self._manifestlog) return memmanifestctx(self._manifestlog)
def copy(self): def copy(self):
memmf = memmanifestctx(self._manifestlog) memmf = memmanifestctx(self._manifestlog)
memmf._manifestdict = self.read().copy() memmf._manifestdict = self.read().copy()
return memmf return memmf
def read(self): def read(self):
return self._manifestdict return self._manifestdict
def write(self, transaction, link, p1, p2, added, removed): def write(self, transaction, link, p1, p2, added, removed):
return self._revlog().add(self._manifestdict, transaction, link, p1, p2, return self._revlog().add(self._manifestdict, transaction, link, p1, p2,
added, removed) added, removed)
@interfaceutil.implementer(repository.imanifestrevisionstored)
class manifestctx(object): class manifestctx(object):
"""A class representing a single revision of a manifest, including its """A class representing a single revision of a manifest, including its
contents, its parent revs, and its linkrev. contents, its parent revs, and its linkrev.
""" """
def __init__(self, manifestlog, node): def __init__(self, manifestlog, node):
self._manifestlog = manifestlog self._manifestlog = manifestlog
self._data = None self._data = None
revlog = self._revlog() revlog = self._revlog()
r = revlog.rev(self._node) r = revlog.rev(self._node)
d = mdiff.patchtext(revlog.revdiff(revlog.deltaparent(r), r)) d = mdiff.patchtext(revlog.revdiff(revlog.deltaparent(r), r))
return manifestdict(d) return manifestdict(d)
def find(self, key): def find(self, key):
return self.read().find(key) return self.read().find(key)
@interfaceutil.implementer(repository.imanifestrevisionwritable)
class memtreemanifestctx(object): class memtreemanifestctx(object):
def __init__(self, manifestlog, dir=''): def __init__(self, manifestlog, dir=''):
self._manifestlog = manifestlog self._manifestlog = manifestlog
self._dir = dir self._dir = dir
self._treemanifest = treemanifest() self._treemanifest = treemanifest()
def _revlog(self): def _revlog(self):
return self._manifestlog._revlog return self._manifestlog._revlog
return self._treemanifest return self._treemanifest
def write(self, transaction, link, p1, p2, added, removed): def write(self, transaction, link, p1, p2, added, removed):
def readtree(dir, node): def readtree(dir, node):
return self._manifestlog.get(dir, node).read() return self._manifestlog.get(dir, node).read()
return self._revlog().add(self._treemanifest, transaction, link, p1, p2, return self._revlog().add(self._treemanifest, transaction, link, p1, p2,
added, removed, readtree=readtree) added, removed, readtree=readtree)
@interfaceutil.implementer(repository.imanifestrevisionstored)
class treemanifestctx(object): class treemanifestctx(object):
def __init__(self, manifestlog, dir, node): def __init__(self, manifestlog, dir, node):
self._manifestlog = manifestlog self._manifestlog = manifestlog
self._dir = dir self._dir = dir
self._data = None self._data = None
self._node = node self._node = node

mercurial/repository.py

""" """
def checksize(): def checksize():
"""Obtain the expected sizes of backing files. """Obtain the expected sizes of backing files.
TODO this is used by verify and it should not be part of the interface. TODO this is used by verify and it should not be part of the interface.
""" """
class idirs(interfaceutil.Interface):
"""Interface representing a collection of directories from paths.
This interface is essentially a derived data structure representing
directories from a collection of paths.
"""
def addpath(path):
"""Add a path to the collection.
All directories in the path will be added to the collection.
"""
def delpath(path):
"""Remove a path from the collection.
If the removal was the last path in a particular directory, the
directory is removed from the collection.
"""
def __iter__():
"""Iterate over the directories in this collection of paths."""
def __contains__(path):
"""Whether a specific directory is in this collection."""
class imanifestdict(interfaceutil.Interface):
"""Interface representing a manifest data structure.
A manifest is effectively a dict mapping paths to entries. Each entry
consists of a binary node and extra flags affecting that entry.
"""
def __getitem__(path):
"""Returns the binary node value for a path in the manifest.
Raises ``KeyError`` if the path does not exist in the manifest.
Equivalent to ``self.find(path)[0]``.
"""
def find(path):
"""Returns the entry for a path in the manifest.
Returns a 2-tuple of (node, flags).
Raises ``KeyError`` if the path does not exist in the manifest.
"""
def __len__():
"""Return the number of entries in the manifest."""
def __nonzero__():
"""Returns True if the manifest has entries, False otherwise."""
__bool__ = __nonzero__
def __setitem__(path, node):
"""Define the node value for a path in the manifest.
If the path is already in the manifest, its flags will be copied to
the new entry.
"""
def __contains__(path):
"""Whether a path exists in the manifest."""
def __delitem__(path):
"""Remove a path from the manifest.
Raises ``KeyError`` if the path is not in the manifest.
"""
def __iter__():
"""Iterate over paths in the manifest."""
def iterkeys():
"""Iterate over paths in the manifest."""
def keys():
"""Obtain a list of paths in the manifest."""
def filesnotin(other, match=None):
"""Obtain the set of paths in this manifest but not in another.
``match`` is an optional matcher function to be applied to both
manifests.
Returns a set of paths.
"""
def dirs():
"""Returns an object implementing the ``idirs`` interface."""
def hasdir(dir):
"""Returns a bool indicating if a directory is in this manifest."""
def matches(match):
"""Generate a new manifest filtered through a matcher.
Returns an object conforming to the ``imanifestdict`` interface.
"""
def walk(match):
"""Generator of paths in manifest satisfying a matcher.
This is equivalent to ``self.matches(match).iterkeys()`` except a new
manifest object is not created.
If the matcher has explicit files listed and they don't exist in
the manifest, ``match.bad()`` is called for each missing file.
"""
def diff(other, match=None, clean=False):
"""Find differences between this manifest and another.
This manifest is compared to ``other``.
If ``match`` is provided, the two manifests are filtered against this
matcher and only entries satisfying the matcher are compared.
If ``clean`` is True, unchanged files are included in the returned
object.
Returns a dict with paths as keys and values of 2-tuples of 2-tuples of
the form ``((node1, flag1), (node2, flag2))`` where ``(node1, flag1)``
represents the node and flags for this manifest and ``(node2, flag2)``
are the same for the other manifest.
"""
def setflag(path, flag):
"""Set the flag value for a given path.
Raises ``KeyError`` if the path is not already in the manifest.
"""
def get(path, default=None):
"""Obtain the node value for a path or a default value if missing."""
def flags(path, default=''):
"""Return the flags value for a path or a default value if missing."""
def copy():
"""Return a copy of this manifest."""
def items():
"""Returns an iterable of (path, node) for items in this manifest."""
def iteritems():
"""Identical to items()."""
def iterentries():
"""Returns an iterable of (path, node, flags) for this manifest.
Similar to ``iteritems()`` except items are a 3-tuple and include
flags.
"""
def text():
"""Obtain the raw data representation for this manifest.
Result is used to create a manifest revision.
"""
def fastdelta(base, changes):
"""Obtain a delta between this manifest and another given changes.
``base`` in the raw data representation for another manifest.
``changes`` is an iterable of ``(path, to_delete)``.
Returns a 2-tuple containing ``bytearray(self.text())`` and the
delta between ``base`` and this manifest.
"""
class imanifestrevisionbase(interfaceutil.Interface):
"""Base interface representing a single revision of a manifest.
Should not be used as a primary interface: should always be inherited
as part of a larger interface.
"""
def new():
"""Obtain a new manifest instance.
Returns an object conforming to the ``imanifestrevisionwritable``
interface. The instance will be associated with the same
``imanifestlog`` collection as this instance.
"""
def copy():
"""Obtain a copy of this manifest instance.
Returns an object conforming to the ``imanifestrevisionwritable``
interface. The instance will be associated with the same
``imanifestlog`` collection as this instance.
"""
def read():
"""Obtain the parsed manifest data structure.
The returned object conforms to the ``imanifestdict`` interface.
"""
class imanifestrevisionstored(imanifestrevisionbase):
"""Interface representing a manifest revision committed to storage."""
def node():
"""The binary node for this manifest."""
parents = interfaceutil.Attribute(
"""List of binary nodes that are parents for this manifest revision."""
)
def readdelta(shallow=False):
"""Obtain the manifest data structure representing changes from parent.
This manifest is compared to its 1st parent. A new manifest representing
those differences is constructed.
The returned object conforms to the ``imanifestdict`` interface.
"""
def readfast(shallow=False):
"""Calls either ``read()`` or ``readdelta()``.
The faster of the two options is called.
"""
def find(key):
"""Calls self.read().find(key)``.
Returns a 2-tuple of ``(node, flags)`` or raises ``KeyError``.
"""
class imanifestrevisionwritable(imanifestrevisionbase):
"""Interface representing a manifest revision that can be committed."""
def write(transaction, linkrev, p1node, p2node, added, removed):
"""Add this revision to storage.
Takes a transaction object, the changeset revision number it will
be associated with, its parent nodes, and lists of added and
removed paths.
Returns the binary node of the created revision.
"""
class imanifestlog(interfaceutil.Interface):
"""Interface representing a collection of manifest snapshots."""
def __getitem__(node):
"""Obtain a manifest instance for a given binary node.
Equivalent to calling ``self.get('', node)``.
The returned object conforms to the ``imanifestrevisionstored``
interface.
"""
def get(dir, node, verify=True):
"""Retrieve the manifest instance for a given directory and binary node.
``node`` always refers to the node of the root manifest (which will be
the only manifest if flat manifests are being used).
If ``dir`` is the empty string, the root manifest is returned. Otherwise
the manifest for the specified directory will be returned (requires
tree manifests).
If ``verify`` is True, ``LookupError`` is raised if the node is not
known.
The returned object conforms to the ``imanifestrevisionstored``
interface.
"""
def clearcaches():
"""Clear caches associated with this collection."""
class completelocalrepository(interfaceutil.Interface): class completelocalrepository(interfaceutil.Interface):
"""Monolithic interface for local repositories. """Monolithic interface for local repositories.
This currently captures the reality of things - not how things should be. This currently captures the reality of things - not how things should be.
""" """
supportedformats = interfaceutil.Attribute( supportedformats = interfaceutil.Attribute(
"""Set of requirements that apply to stream clone. """Set of requirements that apply to stream clone.
obsstore = interfaceutil.Attribute( obsstore = interfaceutil.Attribute(
"""A store of obsolescence data.""") """A store of obsolescence data.""")
changelog = interfaceutil.Attribute( changelog = interfaceutil.Attribute(
"""A handle on the changelog revlog.""") """A handle on the changelog revlog.""")
manifestlog = interfaceutil.Attribute( manifestlog = interfaceutil.Attribute(
"""A handle on the root manifest revlog.""") """An instance conforming to the ``imanifestlog`` interface.
Provides access to manifests for the repository.
""")
dirstate = interfaceutil.Attribute( dirstate = interfaceutil.Attribute(
"""Working directory state.""") """Working directory state.""")
narrowpats = interfaceutil.Attribute( narrowpats = interfaceutil.Attribute(
"""Matcher patterns for this repository's narrowspec.""") """Matcher patterns for this repository's narrowspec.""")
def narrowmatch(): def narrowmatch():

tests/test-check-interfaces.py

from mercurial.thirdparty.zope.interface import ( from mercurial.thirdparty.zope.interface import (
verify as ziverify, verify as ziverify,
) )
from mercurial import ( from mercurial import (
bundlerepo, bundlerepo,
filelog, filelog,
httppeer, httppeer,
localrepo, localrepo,
manifest,
pycompat, pycompat,
repository, repository,
sshpeer, sshpeer,
statichttprepo, statichttprepo,
ui as uimod, ui as uimod,
unionrepo, unionrepo,
vfs as vfsmod, vfs as vfsmod,
wireprotoserver, wireprotoserver,
checkzobject(sshv2) checkzobject(sshv2)
httpv1 = wireprotoserver.httpv1protocolhandler(None, None, None) httpv1 = wireprotoserver.httpv1protocolhandler(None, None, None)
checkzobject(httpv1) checkzobject(httpv1)
httpv2 = wireprotov2server.httpv2protocolhandler(None, None) httpv2 = wireprotov2server.httpv2protocolhandler(None, None)
checkzobject(httpv2) checkzobject(httpv2)
ziverify.verifyClass(repository.ifilestorage, filelog.filelog) ziverify.verifyClass(repository.ifilestorage, filelog.filelog)
ziverify.verifyClass(repository.imanifestdict, manifest.manifestdict)
ziverify.verifyClass(repository.imanifestrevisionstored,
manifest.manifestctx)
ziverify.verifyClass(repository.imanifestrevisionwritable,
manifest.memmanifestctx)
ziverify.verifyClass(repository.imanifestrevisionstored,
manifest.treemanifestctx)
ziverify.verifyClass(repository.imanifestrevisionwritable,
manifest.memtreemanifestctx)
ziverify.verifyClass(repository.imanifestlog, manifest.manifestlog)
vfs = vfsmod.vfs(b'.') vfs = vfsmod.vfs(b'.')
fl = filelog.filelog(vfs, b'dummy.i') fl = filelog.filelog(vfs, b'dummy.i')
checkzobject(fl, allowextra=True) checkzobject(fl, allowextra=True)
# Conforms to imanifestlog.
ml = manifest.manifestlog(vfs, repo)
checkzobject(ml)
checkzobject(repo.manifestlog)
# Conforms to imanifestrevision.
mctx = ml[repo[0].manifestnode()]
checkzobject(mctx)
# Conforms to imanifestrevisionwritable.
checkzobject(mctx.new())
checkzobject(mctx.copy())
# Conforms to imanifestdict.
checkzobject(mctx.read())
main() main()