annotate mercurial/thirdparty/zope/interface/document.py @ 37176:943d77fc07a3

thirdparty: vendor zope.interface 4.4.3 I've been trying to formalize interfaces for various components of Mercurial. So far, we've been using the "abc" package. This package is "good enough" for a lot of tasks. But it quickly falls over. For example, if you declare an @abc.abstractproperty, you must implement that attribute with a @property or the class compile time checking performed by abc will complain. This often forces you to implement dumb @property wrappers to return a _ prefixed attribute of the sane name. That's ugly. I've also wanted to implement automated checking that classes conform to various interfaces and don't expose other "public" attributes. After doing a bit of research and asking around, the general consensus seems to be that zope.interface is the best package for doing interface-based programming in Python. It has built-in support for verifying classes and objects conform to interfaces. It allows an interface's properties to be defined during __init__. There's even an "adapter registry" that allow you to register interfaces and look up which classes implement them. That could potentially be useful for places where our custom registry.py modules currently facilitates central registrations, but at a type level. Imagine extensions providing alternate implementations of things like the local repository interface to allow opening repositories with custom requirements. Anyway, this commit vendors zope.interface 4.4.3. The contents of the source tarball have been copied into mercurial/thirdparty/zope/ without modifications. Test modules have been removed because they are not interesting to us. The LICENSE.txt file has been copied so it lives next to the source. The Python modules don't use relative imports. zope/__init__.py defines a namespace package. So we'll need to modify the source code before this package is usable inside Mercurial. This will be done in subsequent commits. # no-check-commit for various style failures Differential Revision: https://phab.mercurial-scm.org/D2928
author Gregory Szorc <gregory.szorc@gmail.com>
date Wed, 21 Mar 2018 19:48:50 -0700
parents
children 68ee61822182
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
37176
943d77fc07a3 thirdparty: vendor zope.interface 4.4.3
Gregory Szorc <gregory.szorc@gmail.com>
parents:
diff changeset
1 ##############################################################################
943d77fc07a3 thirdparty: vendor zope.interface 4.4.3
Gregory Szorc <gregory.szorc@gmail.com>
parents:
diff changeset
2 #
943d77fc07a3 thirdparty: vendor zope.interface 4.4.3
Gregory Szorc <gregory.szorc@gmail.com>
parents:
diff changeset
3 # Copyright (c) 2001, 2002 Zope Foundation and Contributors.
943d77fc07a3 thirdparty: vendor zope.interface 4.4.3
Gregory Szorc <gregory.szorc@gmail.com>
parents:
diff changeset
4 # All Rights Reserved.
943d77fc07a3 thirdparty: vendor zope.interface 4.4.3
Gregory Szorc <gregory.szorc@gmail.com>
parents:
diff changeset
5 #
943d77fc07a3 thirdparty: vendor zope.interface 4.4.3
Gregory Szorc <gregory.szorc@gmail.com>
parents:
diff changeset
6 # This software is subject to the provisions of the Zope Public License,
943d77fc07a3 thirdparty: vendor zope.interface 4.4.3
Gregory Szorc <gregory.szorc@gmail.com>
parents:
diff changeset
7 # Version 2.1 (ZPL). A copy of the ZPL should accompany this distribution.
943d77fc07a3 thirdparty: vendor zope.interface 4.4.3
Gregory Szorc <gregory.szorc@gmail.com>
parents:
diff changeset
8 # THIS SOFTWARE IS PROVIDED "AS IS" AND ANY AND ALL EXPRESS OR IMPLIED
943d77fc07a3 thirdparty: vendor zope.interface 4.4.3
Gregory Szorc <gregory.szorc@gmail.com>
parents:
diff changeset
9 # WARRANTIES ARE DISCLAIMED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
943d77fc07a3 thirdparty: vendor zope.interface 4.4.3
Gregory Szorc <gregory.szorc@gmail.com>
parents:
diff changeset
10 # WARRANTIES OF TITLE, MERCHANTABILITY, AGAINST INFRINGEMENT, AND FITNESS
943d77fc07a3 thirdparty: vendor zope.interface 4.4.3
Gregory Szorc <gregory.szorc@gmail.com>
parents:
diff changeset
11 # FOR A PARTICULAR PURPOSE.
943d77fc07a3 thirdparty: vendor zope.interface 4.4.3
Gregory Szorc <gregory.szorc@gmail.com>
parents:
diff changeset
12 #
943d77fc07a3 thirdparty: vendor zope.interface 4.4.3
Gregory Szorc <gregory.szorc@gmail.com>
parents:
diff changeset
13 ##############################################################################
943d77fc07a3 thirdparty: vendor zope.interface 4.4.3
Gregory Szorc <gregory.szorc@gmail.com>
parents:
diff changeset
14 """ Pretty-Print an Interface object as structured text (Yum)
943d77fc07a3 thirdparty: vendor zope.interface 4.4.3
Gregory Szorc <gregory.szorc@gmail.com>
parents:
diff changeset
15
943d77fc07a3 thirdparty: vendor zope.interface 4.4.3
Gregory Szorc <gregory.szorc@gmail.com>
parents:
diff changeset
16 This module provides a function, asStructuredText, for rendering an
943d77fc07a3 thirdparty: vendor zope.interface 4.4.3
Gregory Szorc <gregory.szorc@gmail.com>
parents:
diff changeset
17 interface as structured text.
943d77fc07a3 thirdparty: vendor zope.interface 4.4.3
Gregory Szorc <gregory.szorc@gmail.com>
parents:
diff changeset
18 """
943d77fc07a3 thirdparty: vendor zope.interface 4.4.3
Gregory Szorc <gregory.szorc@gmail.com>
parents:
diff changeset
19 import zope.interface
943d77fc07a3 thirdparty: vendor zope.interface 4.4.3
Gregory Szorc <gregory.szorc@gmail.com>
parents:
diff changeset
20
943d77fc07a3 thirdparty: vendor zope.interface 4.4.3
Gregory Szorc <gregory.szorc@gmail.com>
parents:
diff changeset
21
943d77fc07a3 thirdparty: vendor zope.interface 4.4.3
Gregory Szorc <gregory.szorc@gmail.com>
parents:
diff changeset
22 def asStructuredText(I, munge=0, rst=False):
943d77fc07a3 thirdparty: vendor zope.interface 4.4.3
Gregory Szorc <gregory.szorc@gmail.com>
parents:
diff changeset
23 """ Output structured text format. Note, this will whack any existing
943d77fc07a3 thirdparty: vendor zope.interface 4.4.3
Gregory Szorc <gregory.szorc@gmail.com>
parents:
diff changeset
24 'structured' format of the text.
943d77fc07a3 thirdparty: vendor zope.interface 4.4.3
Gregory Szorc <gregory.szorc@gmail.com>
parents:
diff changeset
25
943d77fc07a3 thirdparty: vendor zope.interface 4.4.3
Gregory Szorc <gregory.szorc@gmail.com>
parents:
diff changeset
26 If `rst=True`, then the output will quote all code as inline literals in
943d77fc07a3 thirdparty: vendor zope.interface 4.4.3
Gregory Szorc <gregory.szorc@gmail.com>
parents:
diff changeset
27 accordance with 'reStructuredText' markup principles.
943d77fc07a3 thirdparty: vendor zope.interface 4.4.3
Gregory Szorc <gregory.szorc@gmail.com>
parents:
diff changeset
28 """
943d77fc07a3 thirdparty: vendor zope.interface 4.4.3
Gregory Szorc <gregory.szorc@gmail.com>
parents:
diff changeset
29
943d77fc07a3 thirdparty: vendor zope.interface 4.4.3
Gregory Szorc <gregory.szorc@gmail.com>
parents:
diff changeset
30 if rst:
943d77fc07a3 thirdparty: vendor zope.interface 4.4.3
Gregory Szorc <gregory.szorc@gmail.com>
parents:
diff changeset
31 inline_literal = lambda s: "``%s``" % (s,)
943d77fc07a3 thirdparty: vendor zope.interface 4.4.3
Gregory Szorc <gregory.szorc@gmail.com>
parents:
diff changeset
32 else:
943d77fc07a3 thirdparty: vendor zope.interface 4.4.3
Gregory Szorc <gregory.szorc@gmail.com>
parents:
diff changeset
33 inline_literal = lambda s: s
943d77fc07a3 thirdparty: vendor zope.interface 4.4.3
Gregory Szorc <gregory.szorc@gmail.com>
parents:
diff changeset
34
943d77fc07a3 thirdparty: vendor zope.interface 4.4.3
Gregory Szorc <gregory.szorc@gmail.com>
parents:
diff changeset
35 r = [inline_literal(I.getName())]
943d77fc07a3 thirdparty: vendor zope.interface 4.4.3
Gregory Szorc <gregory.szorc@gmail.com>
parents:
diff changeset
36 outp = r.append
943d77fc07a3 thirdparty: vendor zope.interface 4.4.3
Gregory Szorc <gregory.szorc@gmail.com>
parents:
diff changeset
37 level = 1
943d77fc07a3 thirdparty: vendor zope.interface 4.4.3
Gregory Szorc <gregory.szorc@gmail.com>
parents:
diff changeset
38
943d77fc07a3 thirdparty: vendor zope.interface 4.4.3
Gregory Szorc <gregory.szorc@gmail.com>
parents:
diff changeset
39 if I.getDoc():
943d77fc07a3 thirdparty: vendor zope.interface 4.4.3
Gregory Szorc <gregory.szorc@gmail.com>
parents:
diff changeset
40 outp(_justify_and_indent(_trim_doc_string(I.getDoc()), level))
943d77fc07a3 thirdparty: vendor zope.interface 4.4.3
Gregory Szorc <gregory.szorc@gmail.com>
parents:
diff changeset
41
943d77fc07a3 thirdparty: vendor zope.interface 4.4.3
Gregory Szorc <gregory.szorc@gmail.com>
parents:
diff changeset
42 bases = [base
943d77fc07a3 thirdparty: vendor zope.interface 4.4.3
Gregory Szorc <gregory.szorc@gmail.com>
parents:
diff changeset
43 for base in I.__bases__
943d77fc07a3 thirdparty: vendor zope.interface 4.4.3
Gregory Szorc <gregory.szorc@gmail.com>
parents:
diff changeset
44 if base is not zope.interface.Interface
943d77fc07a3 thirdparty: vendor zope.interface 4.4.3
Gregory Szorc <gregory.szorc@gmail.com>
parents:
diff changeset
45 ]
943d77fc07a3 thirdparty: vendor zope.interface 4.4.3
Gregory Szorc <gregory.szorc@gmail.com>
parents:
diff changeset
46 if bases:
943d77fc07a3 thirdparty: vendor zope.interface 4.4.3
Gregory Szorc <gregory.szorc@gmail.com>
parents:
diff changeset
47 outp(_justify_and_indent("This interface extends:", level, munge))
943d77fc07a3 thirdparty: vendor zope.interface 4.4.3
Gregory Szorc <gregory.szorc@gmail.com>
parents:
diff changeset
48 level += 1
943d77fc07a3 thirdparty: vendor zope.interface 4.4.3
Gregory Szorc <gregory.szorc@gmail.com>
parents:
diff changeset
49 for b in bases:
943d77fc07a3 thirdparty: vendor zope.interface 4.4.3
Gregory Szorc <gregory.szorc@gmail.com>
parents:
diff changeset
50 item = "o %s" % inline_literal(b.getName())
943d77fc07a3 thirdparty: vendor zope.interface 4.4.3
Gregory Szorc <gregory.szorc@gmail.com>
parents:
diff changeset
51 outp(_justify_and_indent(_trim_doc_string(item), level, munge))
943d77fc07a3 thirdparty: vendor zope.interface 4.4.3
Gregory Szorc <gregory.szorc@gmail.com>
parents:
diff changeset
52 level -= 1
943d77fc07a3 thirdparty: vendor zope.interface 4.4.3
Gregory Szorc <gregory.szorc@gmail.com>
parents:
diff changeset
53
943d77fc07a3 thirdparty: vendor zope.interface 4.4.3
Gregory Szorc <gregory.szorc@gmail.com>
parents:
diff changeset
54 namesAndDescriptions = sorted(I.namesAndDescriptions())
943d77fc07a3 thirdparty: vendor zope.interface 4.4.3
Gregory Szorc <gregory.szorc@gmail.com>
parents:
diff changeset
55
943d77fc07a3 thirdparty: vendor zope.interface 4.4.3
Gregory Szorc <gregory.szorc@gmail.com>
parents:
diff changeset
56 outp(_justify_and_indent("Attributes:", level, munge))
943d77fc07a3 thirdparty: vendor zope.interface 4.4.3
Gregory Szorc <gregory.szorc@gmail.com>
parents:
diff changeset
57 level += 1
943d77fc07a3 thirdparty: vendor zope.interface 4.4.3
Gregory Szorc <gregory.szorc@gmail.com>
parents:
diff changeset
58 for name, desc in namesAndDescriptions:
943d77fc07a3 thirdparty: vendor zope.interface 4.4.3
Gregory Szorc <gregory.szorc@gmail.com>
parents:
diff changeset
59 if not hasattr(desc, 'getSignatureString'): # ugh...
943d77fc07a3 thirdparty: vendor zope.interface 4.4.3
Gregory Szorc <gregory.szorc@gmail.com>
parents:
diff changeset
60 item = "%s -- %s" % (inline_literal(desc.getName()),
943d77fc07a3 thirdparty: vendor zope.interface 4.4.3
Gregory Szorc <gregory.szorc@gmail.com>
parents:
diff changeset
61 desc.getDoc() or 'no documentation')
943d77fc07a3 thirdparty: vendor zope.interface 4.4.3
Gregory Szorc <gregory.szorc@gmail.com>
parents:
diff changeset
62 outp(_justify_and_indent(_trim_doc_string(item), level, munge))
943d77fc07a3 thirdparty: vendor zope.interface 4.4.3
Gregory Szorc <gregory.szorc@gmail.com>
parents:
diff changeset
63 level -= 1
943d77fc07a3 thirdparty: vendor zope.interface 4.4.3
Gregory Szorc <gregory.szorc@gmail.com>
parents:
diff changeset
64
943d77fc07a3 thirdparty: vendor zope.interface 4.4.3
Gregory Szorc <gregory.szorc@gmail.com>
parents:
diff changeset
65 outp(_justify_and_indent("Methods:", level, munge))
943d77fc07a3 thirdparty: vendor zope.interface 4.4.3
Gregory Szorc <gregory.szorc@gmail.com>
parents:
diff changeset
66 level += 1
943d77fc07a3 thirdparty: vendor zope.interface 4.4.3
Gregory Szorc <gregory.szorc@gmail.com>
parents:
diff changeset
67 for name, desc in namesAndDescriptions:
943d77fc07a3 thirdparty: vendor zope.interface 4.4.3
Gregory Szorc <gregory.szorc@gmail.com>
parents:
diff changeset
68 if hasattr(desc, 'getSignatureString'): # ugh...
943d77fc07a3 thirdparty: vendor zope.interface 4.4.3
Gregory Szorc <gregory.szorc@gmail.com>
parents:
diff changeset
69 _call = "%s%s" % (desc.getName(), desc.getSignatureString())
943d77fc07a3 thirdparty: vendor zope.interface 4.4.3
Gregory Szorc <gregory.szorc@gmail.com>
parents:
diff changeset
70 item = "%s -- %s" % (inline_literal(_call),
943d77fc07a3 thirdparty: vendor zope.interface 4.4.3
Gregory Szorc <gregory.szorc@gmail.com>
parents:
diff changeset
71 desc.getDoc() or 'no documentation')
943d77fc07a3 thirdparty: vendor zope.interface 4.4.3
Gregory Szorc <gregory.szorc@gmail.com>
parents:
diff changeset
72 outp(_justify_and_indent(_trim_doc_string(item), level, munge))
943d77fc07a3 thirdparty: vendor zope.interface 4.4.3
Gregory Szorc <gregory.szorc@gmail.com>
parents:
diff changeset
73
943d77fc07a3 thirdparty: vendor zope.interface 4.4.3
Gregory Szorc <gregory.szorc@gmail.com>
parents:
diff changeset
74 return "\n\n".join(r) + "\n\n"
943d77fc07a3 thirdparty: vendor zope.interface 4.4.3
Gregory Szorc <gregory.szorc@gmail.com>
parents:
diff changeset
75
943d77fc07a3 thirdparty: vendor zope.interface 4.4.3
Gregory Szorc <gregory.szorc@gmail.com>
parents:
diff changeset
76
943d77fc07a3 thirdparty: vendor zope.interface 4.4.3
Gregory Szorc <gregory.szorc@gmail.com>
parents:
diff changeset
77 def asReStructuredText(I, munge=0):
943d77fc07a3 thirdparty: vendor zope.interface 4.4.3
Gregory Szorc <gregory.szorc@gmail.com>
parents:
diff changeset
78 """ Output reStructuredText format. Note, this will whack any existing
943d77fc07a3 thirdparty: vendor zope.interface 4.4.3
Gregory Szorc <gregory.szorc@gmail.com>
parents:
diff changeset
79 'structured' format of the text."""
943d77fc07a3 thirdparty: vendor zope.interface 4.4.3
Gregory Szorc <gregory.szorc@gmail.com>
parents:
diff changeset
80 return asStructuredText(I, munge=munge, rst=True)
943d77fc07a3 thirdparty: vendor zope.interface 4.4.3
Gregory Szorc <gregory.szorc@gmail.com>
parents:
diff changeset
81
943d77fc07a3 thirdparty: vendor zope.interface 4.4.3
Gregory Szorc <gregory.szorc@gmail.com>
parents:
diff changeset
82
943d77fc07a3 thirdparty: vendor zope.interface 4.4.3
Gregory Szorc <gregory.szorc@gmail.com>
parents:
diff changeset
83 def _trim_doc_string(text):
943d77fc07a3 thirdparty: vendor zope.interface 4.4.3
Gregory Szorc <gregory.szorc@gmail.com>
parents:
diff changeset
84 """ Trims a doc string to make it format
943d77fc07a3 thirdparty: vendor zope.interface 4.4.3
Gregory Szorc <gregory.szorc@gmail.com>
parents:
diff changeset
85 correctly with structured text. """
943d77fc07a3 thirdparty: vendor zope.interface 4.4.3
Gregory Szorc <gregory.szorc@gmail.com>
parents:
diff changeset
86
943d77fc07a3 thirdparty: vendor zope.interface 4.4.3
Gregory Szorc <gregory.szorc@gmail.com>
parents:
diff changeset
87 lines = text.replace('\r\n', '\n').split('\n')
943d77fc07a3 thirdparty: vendor zope.interface 4.4.3
Gregory Szorc <gregory.szorc@gmail.com>
parents:
diff changeset
88 nlines = [lines.pop(0)]
943d77fc07a3 thirdparty: vendor zope.interface 4.4.3
Gregory Szorc <gregory.szorc@gmail.com>
parents:
diff changeset
89 if lines:
943d77fc07a3 thirdparty: vendor zope.interface 4.4.3
Gregory Szorc <gregory.szorc@gmail.com>
parents:
diff changeset
90 min_indent = min([len(line) - len(line.lstrip())
943d77fc07a3 thirdparty: vendor zope.interface 4.4.3
Gregory Szorc <gregory.szorc@gmail.com>
parents:
diff changeset
91 for line in lines])
943d77fc07a3 thirdparty: vendor zope.interface 4.4.3
Gregory Szorc <gregory.szorc@gmail.com>
parents:
diff changeset
92 for line in lines:
943d77fc07a3 thirdparty: vendor zope.interface 4.4.3
Gregory Szorc <gregory.szorc@gmail.com>
parents:
diff changeset
93 nlines.append(line[min_indent:])
943d77fc07a3 thirdparty: vendor zope.interface 4.4.3
Gregory Szorc <gregory.szorc@gmail.com>
parents:
diff changeset
94
943d77fc07a3 thirdparty: vendor zope.interface 4.4.3
Gregory Szorc <gregory.szorc@gmail.com>
parents:
diff changeset
95 return '\n'.join(nlines)
943d77fc07a3 thirdparty: vendor zope.interface 4.4.3
Gregory Szorc <gregory.szorc@gmail.com>
parents:
diff changeset
96
943d77fc07a3 thirdparty: vendor zope.interface 4.4.3
Gregory Szorc <gregory.szorc@gmail.com>
parents:
diff changeset
97
943d77fc07a3 thirdparty: vendor zope.interface 4.4.3
Gregory Szorc <gregory.szorc@gmail.com>
parents:
diff changeset
98 def _justify_and_indent(text, level, munge=0, width=72):
943d77fc07a3 thirdparty: vendor zope.interface 4.4.3
Gregory Szorc <gregory.szorc@gmail.com>
parents:
diff changeset
99 """ indent and justify text, rejustify (munge) if specified """
943d77fc07a3 thirdparty: vendor zope.interface 4.4.3
Gregory Szorc <gregory.szorc@gmail.com>
parents:
diff changeset
100
943d77fc07a3 thirdparty: vendor zope.interface 4.4.3
Gregory Szorc <gregory.szorc@gmail.com>
parents:
diff changeset
101 indent = " " * level
943d77fc07a3 thirdparty: vendor zope.interface 4.4.3
Gregory Szorc <gregory.szorc@gmail.com>
parents:
diff changeset
102
943d77fc07a3 thirdparty: vendor zope.interface 4.4.3
Gregory Szorc <gregory.szorc@gmail.com>
parents:
diff changeset
103 if munge:
943d77fc07a3 thirdparty: vendor zope.interface 4.4.3
Gregory Szorc <gregory.szorc@gmail.com>
parents:
diff changeset
104 lines = []
943d77fc07a3 thirdparty: vendor zope.interface 4.4.3
Gregory Szorc <gregory.szorc@gmail.com>
parents:
diff changeset
105 line = indent
943d77fc07a3 thirdparty: vendor zope.interface 4.4.3
Gregory Szorc <gregory.szorc@gmail.com>
parents:
diff changeset
106 text = text.split()
943d77fc07a3 thirdparty: vendor zope.interface 4.4.3
Gregory Szorc <gregory.szorc@gmail.com>
parents:
diff changeset
107
943d77fc07a3 thirdparty: vendor zope.interface 4.4.3
Gregory Szorc <gregory.szorc@gmail.com>
parents:
diff changeset
108 for word in text:
943d77fc07a3 thirdparty: vendor zope.interface 4.4.3
Gregory Szorc <gregory.szorc@gmail.com>
parents:
diff changeset
109 line = ' '.join([line, word])
943d77fc07a3 thirdparty: vendor zope.interface 4.4.3
Gregory Szorc <gregory.szorc@gmail.com>
parents:
diff changeset
110 if len(line) > width:
943d77fc07a3 thirdparty: vendor zope.interface 4.4.3
Gregory Szorc <gregory.szorc@gmail.com>
parents:
diff changeset
111 lines.append(line)
943d77fc07a3 thirdparty: vendor zope.interface 4.4.3
Gregory Szorc <gregory.szorc@gmail.com>
parents:
diff changeset
112 line = indent
943d77fc07a3 thirdparty: vendor zope.interface 4.4.3
Gregory Szorc <gregory.szorc@gmail.com>
parents:
diff changeset
113 else:
943d77fc07a3 thirdparty: vendor zope.interface 4.4.3
Gregory Szorc <gregory.szorc@gmail.com>
parents:
diff changeset
114 lines.append(line)
943d77fc07a3 thirdparty: vendor zope.interface 4.4.3
Gregory Szorc <gregory.szorc@gmail.com>
parents:
diff changeset
115
943d77fc07a3 thirdparty: vendor zope.interface 4.4.3
Gregory Szorc <gregory.szorc@gmail.com>
parents:
diff changeset
116 return '\n'.join(lines)
943d77fc07a3 thirdparty: vendor zope.interface 4.4.3
Gregory Szorc <gregory.szorc@gmail.com>
parents:
diff changeset
117
943d77fc07a3 thirdparty: vendor zope.interface 4.4.3
Gregory Szorc <gregory.szorc@gmail.com>
parents:
diff changeset
118 else:
943d77fc07a3 thirdparty: vendor zope.interface 4.4.3
Gregory Szorc <gregory.szorc@gmail.com>
parents:
diff changeset
119 return indent + \
943d77fc07a3 thirdparty: vendor zope.interface 4.4.3
Gregory Szorc <gregory.szorc@gmail.com>
parents:
diff changeset
120 text.strip().replace("\r\n", "\n") .replace("\n", "\n" + indent)