16098868126

Committed 14 Apr 2025 06:50AM UTC coverage: 87.385%. Remained the same

Build # 16098868126

Build Type

push

github

Committed by

icemac

Commit Message

Back to development: 5.1

Run Details

561 of 792 branches covered (70.83%)

Branch coverage included in aggregate %.

3990 of 4416 relevant lines covered (90.35%)

0.9 hits per line

Source File
Press 'n' to go to next uncovered line, 'b' for previous

17.33

/src/z3c/rml/reference.py

##############################################################################
#
# Copyright (c) 2007 Zope Foundation and Contributors.
# All Rights Reserved.
#
# This software is subject to the provisions of the Zope Public License,
# Version 2.1 (ZPL).  A copy of the ZPL should accompany this distribution.
# THIS SOFTWARE IS PROVIDED "AS IS" AND ANY AND ALL EXPRESS OR IMPLIED
# WARRANTIES ARE DISCLAIMED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
# WARRANTIES OF TITLE, MERCHANTABILITY, AGAINST INFRINGEMENT, AND FITNESS
# FOR A PARTICULAR PURPOSE.
#
##############################################################################
"""RML Reference Generator
"""
import os
import re
from xml.sax import saxutils

import pygments.token
import zope.schema
import zope.schema.interfaces
from lxml import etree
from pygments.lexers import XmlLexer

from z3c.rml import __version__
from z3c.rml import attr
from z3c.rml import document
from z3c.rml import interfaces
from z3c.rml import pagetemplate


INPUT_URL = ('https://github.com/zopefoundation/z3c.rml/blob/master/src/z3c/'
             'rml/tests/input/%s')
EXPECTED_URL = (
    'https://github.com/zopefoundation/z3c.rml/blob/master/src/z3c/'
    'rml/tests/expected/%s?raw=true')

EXAMPLES_DIRECTORY = os.path.join(os.path.dirname(__file__), 'tests', 'input')
IGNORE_ATTRIBUTES = ('RMLAttribute', 'BaseChoice')
CONTENT_FIELD_TYPES = (
    attr.TextNode, attr.TextNodeSequence, attr.TextNodeGrid,
    attr.RawXMLContent, attr.XMLContent)
STYLES_FORMATTING = {
    pygments.token.Name.Tag: ('<font textColor="red">', '</font>'),
    pygments.token.Literal.String: ('<font textColor="blue">', '</font>'),
}
EXAMPLE_NS = 'http://namespaces.zope.org/rml/doc'
EXAMPLE_ATTR_NAME = '{%s}example' % EXAMPLE_NS


def dedent(rml):
    spaces = re.findall('\n( *)<', rml)
    if not spaces:
        return rml
    least = min([len(s) for s in spaces if s != ''])
    return rml.replace('\n' + ' ' * least, '\n')


def enforceColumns(rml, columns=80):
    result = []
    for line in rml.split('\n'):
        if len(line) <= columns:
            result.append(line)
            continue
        # Determine the indentation for all other lines
        lineStart = re.findall('^( *<[a-zA-Z0-9]+ )', line)
        lineIndent = 0
        if lineStart:
            lineIndent = len(lineStart[0])
        # Create lines having at most the specified number of columns
        while len(line) > columns:
            end = line[:columns].rfind(' ')
            result.append(line[:end])
            line = ' ' * lineIndent + line[end + 1:]
        result.append(line)

    return '\n'.join(result)


def highlightRML(rml):
    lexer = XmlLexer()
    styledRml = ''
    for ttype, token in lexer.get_tokens(rml):
        start, end = STYLES_FORMATTING.get(ttype, ('', ''))
        styledRml += start + saxutils.escape(token) + end
    return styledRml


def removeDocAttributes(elem):
    for name in elem.attrib.keys():
        if name.startswith('{' + EXAMPLE_NS + '}'):
            del elem.attrib[name]
    for child in elem.getchildren():
        removeDocAttributes(child)


def getAttributeTypes():
    types = []
    candidates = sorted(attr.__dict__.items(), key=lambda e: e[0])
    for name, candidate in candidates:
        if not (isinstance(candidate, type) and
                zope.schema.interfaces.IField.implementedBy(candidate) and
                name not in IGNORE_ATTRIBUTES):
            continue
        types.append({
            'name': name,
            'description': candidate.__doc__
        })
    return types


def formatField(field):
    return field.__class__.__name__


def formatChoice(field):
    choices = ', '.join([repr(choice) for choice in field.choices.keys()])
    return f'{field.__class__.__name__} of ({choices})'


def formatSequence(field):
    vtFormatter = typeFormatters.get(field.value_type.__class__, formatField)
    return '{} of {}'.format(
        field.__class__.__name__, vtFormatter(field.value_type))


def formatGrid(field):
    vtFormatter = typeFormatters.get(field.value_type.__class__, formatField)
    return '%s with %i cols of %s' % (
        field.__class__.__name__, field.columns, vtFormatter(field.value_type))


def formatCombination(field):
    vts = [typeFormatters.get(vt.__class__, formatField)(vt)
           for vt in field.value_types]
    return '{} of {}'.format(field.__class__.__name__, ', '.join(vts))


typeFormatters = {
    attr.Choice: formatChoice,
    attr.Sequence: formatSequence,
    attr.Combination: formatCombination,
    attr.TextNodeSequence: formatSequence,
    attr.TextNodeGrid: formatGrid}


def processSignature(name, signature, queue, examples, directives=None):
    if directives is None:
        directives = {}
    # Process this directive
    if signature not in directives:
        info = {'name': name, 'description': signature.getDoc(),
                'id': str(hash(signature)), 'deprecated': False}
        # If directive is deprecated, then add some info
        if interfaces.IDeprecatedDirective.providedBy(signature):
            info['deprecated'] = True
            info['reason'] = signature.getTaggedValue('deprecatedReason')
        attrs = []
        content = None
        for fname, field in zope.schema.getFieldsInOrder(signature):
            # Handle the case, where the field describes the content
            typeFormatter = typeFormatters.get(field.__class__, formatField)
            fieldInfo = {
                'name': fname,
                'type': typeFormatter(field),
                'title': field.title,
                'description': field.description,
                'required': field.required,
                'deprecated': False,
            }
            if field.__class__ in CONTENT_FIELD_TYPES:
                content = fieldInfo
            else:
                attrs.append(fieldInfo)

            # Add a separate entry for the deprecated field
            if interfaces.IDeprecated.providedBy(field):
                deprFieldInfo = fieldInfo.copy()
                deprFieldInfo['deprecated'] = True
                deprFieldInfo['name'] = field.deprecatedName
                deprFieldInfo['reason'] = field.deprecatedReason
                attrs.append(deprFieldInfo)

        info['attributes'] = attrs
        info['content'] = content
        # Examples can be either gotten by interface path or tag name
        ifacePath = signature.__module__ + '.' + signature.__name__
        if ifacePath in examples:
            info['examples'] = examples[ifacePath]
        else:
            info['examples'] = examples.get(name, None)

        subs = []
        for occurence in signature.queryTaggedValue('directives', ()):
            subs.append({
                'name': occurence.tag,
                'occurence': occurence.__class__.__name__,
                'deprecated': interfaces.IDeprecatedDirective.providedBy(
                    occurence.signature),
                'id': str(hash(occurence.signature))
            })
        info['sub-directives'] = subs
        directives[signature] = info

        # Process Children
        for occurence in signature.queryTaggedValue('directives', ()):
            queue.append((occurence.tag, occurence.signature))


def extractExamples(directory):
    examples = {}
    for filename in os.listdir(directory):
        if not filename.endswith('.rml'):
            continue
        rmlFile = open(os.path.join(directory, filename), 'rb')
        root = etree.parse(rmlFile).getroot()
        elements = root.xpath('//@doc:example/parent::*',
                              namespaces={'doc': EXAMPLE_NS})
        # Phase 1: Collect all elements
        for elem in elements:
            demoTag = elem.get(EXAMPLE_ATTR_NAME) or elem.tag
            elemExamples = examples.setdefault(demoTag, [])
            elemExamples.append({
                'filename': filename,
                'line': elem.sourceline,
                'element': elem,
                'rmlurl': INPUT_URL % filename,
                'pdfurl': EXPECTED_URL % (filename[:-4] + '.pdf')
            })
        # Phase 2: Render all elements
        removeDocAttributes(root)
        for dirExamples in examples.values():
            for example in dirExamples:
                xml = etree.tounicode(example['element']).strip()
                xml = re.sub(
                    ' ?xmlns:doc="http://namespaces.zope.org/rml/doc"', '', xml
                )
                xml = dedent(xml)
                xml = enforceColumns(xml, 80)
                xml = highlightRML(xml)
                example['code'] = xml

        rmlFile.close()

    return examples


def main(outPath=None):
    examples = extractExamples(EXAMPLES_DIRECTORY)

    template = pagetemplate.RMLPageTemplateFile('reference.pt')

    directives = {}
    queue = [('document', document.IDocument)]
    while queue:
        tag, sig = queue.pop()
        processSignature(tag, sig, queue, examples, directives)
    directives = sorted(directives.values(), key=lambda d: d['name'])

    pdf = template(
        version=__version__,
        types=getAttributeTypes(),
        directives=directives)
    file_ = open(outPath or 'rml-reference.pdf', 'wb')
    file_.write(pdf)
    file_.close()

1	##############################################################################
2	#
3	# Copyright (c) 2007 Zope Foundation and Contributors.
4	# All Rights Reserved.
5	#
6	# This software is subject to the provisions of the Zope Public License,
7	# Version 2.1 (ZPL). A copy of the ZPL should accompany this distribution.
8	# THIS SOFTWARE IS PROVIDED "AS IS" AND ANY AND ALL EXPRESS OR IMPLIED
9	# WARRANTIES ARE DISCLAIMED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
10	# WARRANTIES OF TITLE, MERCHANTABILITY, AGAINST INFRINGEMENT, AND FITNESS
11	# FOR A PARTICULAR PURPOSE.
12	#
13	##############################################################################
14	"""RML Reference Generator
15	"""
16	import os	1✔
17	import re	1✔
18	from xml.sax import saxutils	1✔
19
20	import pygments.token	1✔
21	import zope.schema	1✔
22	import zope.schema.interfaces	1✔
23	from lxml import etree	1✔
24	from pygments.lexers import XmlLexer	1✔
25
26	from z3c.rml import __version__	1✔
27	from z3c.rml import attr	1✔
28	from z3c.rml import document	1✔
29	from z3c.rml import interfaces	1✔
30	from z3c.rml import pagetemplate	1✔
31
32
33	INPUT_URL = ('https://github.com/zopefoundation/z3c.rml/blob/master/src/z3c/'	1✔
34	'rml/tests/input/%s')
35	EXPECTED_URL = (	1✔
36	'https://github.com/zopefoundation/z3c.rml/blob/master/src/z3c/'
37	'rml/tests/expected/%s?raw=true')
38
39	EXAMPLES_DIRECTORY = os.path.join(os.path.dirname(__file__), 'tests', 'input')	1✔
40	IGNORE_ATTRIBUTES = ('RMLAttribute', 'BaseChoice')	1✔
41	CONTENT_FIELD_TYPES = (	1✔
42	attr.TextNode, attr.TextNodeSequence, attr.TextNodeGrid,
43	attr.RawXMLContent, attr.XMLContent)
44	STYLES_FORMATTING = {	1✔
45	pygments.token.Name.Tag: ('<font textColor="red">', '</font>'),
46	pygments.token.Literal.String: ('<font textColor="blue">', '</font>'),
47	}
48	EXAMPLE_NS = 'http://namespaces.zope.org/rml/doc'	1✔
49	EXAMPLE_ATTR_NAME = '{%s}example' % EXAMPLE_NS	1✔
50
51
52	def dedent(rml):	1✔
53	spaces = re.findall('\n( *)<', rml)	×
54	if not spaces:	×
55	return rml	×
56	least = min([len(s) for s in spaces if s != ''])	×
57	return rml.replace('\n' + ' ' * least, '\n')	×
58
59
60	def enforceColumns(rml, columns=80):	1✔
61	result = []	×
62	for line in rml.split('\n'):	×
63	if len(line) <= columns:	×
64	result.append(line)	×
65	continue	×
66	# Determine the indentation for all other lines
67	lineStart = re.findall('^( *<[a-zA-Z0-9]+ )', line)	×
68	lineIndent = 0	×
69	if lineStart:	×
70	lineIndent = len(lineStart[0])	×
71	# Create lines having at most the specified number of columns
72	while len(line) > columns:	×
73	end = line[:columns].rfind(' ')	×
74	result.append(line[:end])	×
75	line = ' ' * lineIndent + line[end + 1:]	×
76	result.append(line)	×
77
78	return '\n'.join(result)	×
79
80
81	def highlightRML(rml):	1✔
82	lexer = XmlLexer()	×
83	styledRml = ''	×
84	for ttype, token in lexer.get_tokens(rml):	×
85	start, end = STYLES_FORMATTING.get(ttype, ('', ''))	×
86	styledRml += start + saxutils.escape(token) + end	×
87	return styledRml	×
88
89
90	def removeDocAttributes(elem):	1✔
91	for name in elem.attrib.keys():	×
92	if name.startswith('{' + EXAMPLE_NS + '}'):	×
93	del elem.attrib[name]	×
94	for child in elem.getchildren():	×
95	removeDocAttributes(child)	×
96
97
98	def getAttributeTypes():	1✔
99	types = []	×
100	candidates = sorted(attr.__dict__.items(), key=lambda e: e[0])	×
101	for name, candidate in candidates:	×
102	if not (isinstance(candidate, type) and	×
103	zope.schema.interfaces.IField.implementedBy(candidate) and
104	name not in IGNORE_ATTRIBUTES):
105	continue	×
106	types.append({	×
107	'name': name,
108	'description': candidate.__doc__
109	})
110	return types	×
111
112
113	def formatField(field):	1✔
114	return field.__class__.__name__	×
115
116
117	def formatChoice(field):	1✔
118	choices = ', '.join([repr(choice) for choice in field.choices.keys()])	×
119	return f'{field.__class__.__name__} of ({choices})'	×
120
121
122	def formatSequence(field):	1✔
123	vtFormatter = typeFormatters.get(field.value_type.__class__, formatField)	×
124	return '{} of {}'.format(	×
125	field.__class__.__name__, vtFormatter(field.value_type))
126
127
128	def formatGrid(field):	1✔
129	vtFormatter = typeFormatters.get(field.value_type.__class__, formatField)	×
130	return '%s with %i cols of %s' % (	×
131	field.__class__.__name__, field.columns, vtFormatter(field.value_type))
132
133
134	def formatCombination(field):	1✔
135	vts = [typeFormatters.get(vt.__class__, formatField)(vt)	×
136	for vt in field.value_types]
137	return '{} of {}'.format(field.__class__.__name__, ', '.join(vts))	×
138
139
140	typeFormatters = {	1✔
141	attr.Choice: formatChoice,
142	attr.Sequence: formatSequence,
143	attr.Combination: formatCombination,
144	attr.TextNodeSequence: formatSequence,
145	attr.TextNodeGrid: formatGrid}
146
147
148	def processSignature(name, signature, queue, examples, directives=None):	1✔
149	if directives is None:	×
150	directives = {}	×
151	# Process this directive
152	if signature not in directives:	×
153	info = {'name': name, 'description': signature.getDoc(),	×
154	'id': str(hash(signature)), 'deprecated': False}
155	# If directive is deprecated, then add some info
156	if interfaces.IDeprecatedDirective.providedBy(signature):	×
157	info['deprecated'] = True	×
158	info['reason'] = signature.getTaggedValue('deprecatedReason')	×
159	attrs = []	×
160	content = None	×
161	for fname, field in zope.schema.getFieldsInOrder(signature):	×
162	# Handle the case, where the field describes the content
163	typeFormatter = typeFormatters.get(field.__class__, formatField)	×
164	fieldInfo = {	×
165	'name': fname,
166	'type': typeFormatter(field),
167	'title': field.title,
168	'description': field.description,
169	'required': field.required,
170	'deprecated': False,
171	}
172	if field.__class__ in CONTENT_FIELD_TYPES:	×
173	content = fieldInfo	×
174	else:
175	attrs.append(fieldInfo)	×
176
177	# Add a separate entry for the deprecated field
178	if interfaces.IDeprecated.providedBy(field):	×
179	deprFieldInfo = fieldInfo.copy()	×
180	deprFieldInfo['deprecated'] = True	×
181	deprFieldInfo['name'] = field.deprecatedName	×
182	deprFieldInfo['reason'] = field.deprecatedReason	×
183	attrs.append(deprFieldInfo)	×
184
185	info['attributes'] = attrs	×
186	info['content'] = content	×
187	# Examples can be either gotten by interface path or tag name
188	ifacePath = signature.__module__ + '.' + signature.__name__	×
189	if ifacePath in examples:	×
190	info['examples'] = examples[ifacePath]	×
191	else:
192	info['examples'] = examples.get(name, None)	×
193
194	subs = []	×
195	for occurence in signature.queryTaggedValue('directives', ()):	×
196	subs.append({	×
197	'name': occurence.tag,
198	'occurence': occurence.__class__.__name__,
199	'deprecated': interfaces.IDeprecatedDirective.providedBy(
200	occurence.signature),
201	'id': str(hash(occurence.signature))
202	})
203	info['sub-directives'] = subs	×
204	directives[signature] = info	×
205
206	# Process Children
207	for occurence in signature.queryTaggedValue('directives', ()):	×
208	queue.append((occurence.tag, occurence.signature))	×
209
210
211	def extractExamples(directory):	1✔
212	examples = {}	×
213	for filename in os.listdir(directory):	×
214	if not filename.endswith('.rml'):	×
215	continue	×
216	rmlFile = open(os.path.join(directory, filename), 'rb')	×
217	root = etree.parse(rmlFile).getroot()	×
218	elements = root.xpath('//@doc:example/parent::*',	×
219	namespaces={'doc': EXAMPLE_NS})
220	# Phase 1: Collect all elements
221	for elem in elements:	×
222	demoTag = elem.get(EXAMPLE_ATTR_NAME) or elem.tag	×
223	elemExamples = examples.setdefault(demoTag, [])	×
224	elemExamples.append({	×
225	'filename': filename,
226	'line': elem.sourceline,
227	'element': elem,
228	'rmlurl': INPUT_URL % filename,
229	'pdfurl': EXPECTED_URL % (filename[:-4] + '.pdf')
230	})
231	# Phase 2: Render all elements
232	removeDocAttributes(root)	×
233	for dirExamples in examples.values():	×
234	for example in dirExamples:	×
235	xml = etree.tounicode(example['element']).strip()	×
236	xml = re.sub(	×
237	' ?xmlns:doc="http://namespaces.zope.org/rml/doc"', '', xml
238	)
239	xml = dedent(xml)	×
240	xml = enforceColumns(xml, 80)	×
241	xml = highlightRML(xml)	×
242	example['code'] = xml	×
243
244	rmlFile.close()	×
245
246	return examples	×
247
248
249	def main(outPath=None):	1✔
250	examples = extractExamples(EXAMPLES_DIRECTORY)	×
251
252	template = pagetemplate.RMLPageTemplateFile('reference.pt')	×
253
254	directives = {}	×
255	queue = [('document', document.IDocument)]	×
256	while queue:	×
257	tag, sig = queue.pop()	×
258	processSignature(tag, sig, queue, examples, directives)	×
259	directives = sorted(directives.values(), key=lambda d: d['name'])	×
260
261	pdf = template(	×
262	version=__version__,
263	types=getAttributeTypes(),
264	directives=directives)
265	file_ = open(outPath or 'rml-reference.pdf', 'wb')	×
266	file_.write(pdf)	×
267	file_.close()	×

zopefoundation / z3c.rml / 16098868126

Source File Press 'n' to go to next uncovered line, 'b' for previous

Source File
Press 'n' to go to next uncovered line, 'b' for previous