def test_creates_correct_path_to_examples_based_on_service_name(self):
path = os.sep.join(
[os.path.dirname(boto3.__file__), 'examples', 'myservice.rst'])
path = os.path.realpath(path)
with mock.patch('os.path.isfile') as isfile:
isfile.return_value = False
s = ServiceDocumenter('myservice', self.session)
s.document_service()
assert isfile.call_args_list[-1] == mock.call(path)
def test_creates_correct_path_to_examples_based_on_service_name(self):
path = os.sep.join([os.path.dirname(boto3.__file__),
'examples', 'myservice.rst'])
path = os.path.realpath(path)
with mock.patch('os.path.isfile') as isfile:
isfile.return_value = False
s = ServiceDocumenter('myservice', self.session)
s.document_service()
self.assertEqual(
isfile.call_args_list[-1],
mock.call(path))
def test_injects_examples_when_found(self):
examples_path = os.sep.join(
[os.path.dirname(__file__), '..', 'data', 'examples'])
service_documenter = ServiceDocumenter('myservice', self.session)
service_documenter.EXAMPLE_PATH = examples_path
contents = service_documenter.document_service().decode('utf-8')
assert 'This is an example' in contents
assert 'This is for another service' not in contents
def test_document_service_no_waiter(self):
# Delete the resource model so that the resource is not documented
# as it may try to look at the waiter model during documentation.
os.remove(self.resource_model_file)
os.remove(self.waiter_model_file)
service_documenter = ServiceDocumenter('myservice', self.session)
contents = service_documenter.document_service().decode('utf-8')
assert 'Waiters' not in contents
def test_document_service_no_paginators(self):
# Delete the resource model so that the resource is not documented
# as it may try to look at the paginator model during documentation.
os.remove(self.resource_model_file)
os.remove(self.paginator_model_file)
service_documenter = ServiceDocumenter('myservice')
contents = service_documenter.document_service().decode('utf-8')
self.assertNotIn('Paginators', contents)
def test_document_service_no_waiter(self):
# Delete the resource model so that the resource is not documented
# as it may try to look at the waiter model during documentation.
os.remove(self.resource_model_file)
os.remove(self.waiter_model_file)
service_documenter = ServiceDocumenter('myservice', self.session)
contents = service_documenter.document_service().decode('utf-8')
self.assertNotIn('Waiters', contents)
def test_document_service_no_paginators(self):
# Delete the resource model so that the resource is not documented
# as it may try to look at the paginator model during documentation.
os.remove(self.resource_model_file)
os.remove(self.paginator_model_file)
service_documenter = ServiceDocumenter('myservice', self.session)
contents = service_documenter.document_service().decode('utf-8')
self.assertNotIn('Paginators', contents)
def test_injects_examples_when_found(self):
examples_path = os.sep.join([os.path.dirname(__file__), '..', 'data',
'examples'])
service_documenter = ServiceDocumenter(
'myservice', self.session)
service_documenter.EXAMPLE_PATH = examples_path
contents = service_documenter.document_service().decode('utf-8')
self.assertIn('This is an example', contents)
self.assertNotIn('This is for another service', contents)
class TestS3Customizations(BaseDocsFunctionalTests):
def setUp(self):
self.documenter = ServiceDocumenter('s3')
self.generated_contents = self.documenter.document_service()
self.generated_contents = self.generated_contents.decode('utf-8')
def test_file_transfer_methods_are_documented(self):
self.assert_contains_lines_in_order([
'.. py:class:: S3.Client', ' * :py:meth:`download_file`',
' * :py:meth:`upload_file`', ' .. py:method:: download_file(',
' .. py:method:: upload_file('
], self.generated_contents)
class TestS3Customizations(BaseDocsFunctionalTests):
def setUp(self):
self.documenter = ServiceDocumenter('s3')
self.generated_contents = self.documenter.document_service()
self.generated_contents = self.generated_contents.decode('utf-8')
def test_file_transfer_methods_are_documented(self):
self.assert_contains_lines_in_order([
'.. py:class:: S3.Client',
' * :py:meth:`download_file`',
' * :py:meth:`upload_file`',
' .. py:method:: download_file(',
' .. py:method:: upload_file('],
self.generated_contents
)
class TestInstanceDeleteTags(BaseDocsFunctionalTests):
def setUp(self):
self.documenter = ServiceDocumenter(
'ec2', session=Session(region_name='us-east-1'))
self.generated_contents = self.documenter.document_service()
self.generated_contents = self.generated_contents.decode('utf-8')
def test_delete_tags_method_is_documented(self):
contents = self.get_class_document_block(
'EC2.Instance', self.generated_contents)
method_contents = self.get_method_document_block(
'delete_tags', contents)
self.assert_contains_lines_in_order([
'response = instance.delete_tags(',
'DryRun=True|False,',
'Tags=[',
], method_contents)
class TestDynamoDBCustomizations(BaseDocsFunctionalTests):
def setUp(self):
self.documenter = ServiceDocumenter('dynamodb')
self.generated_contents = self.documenter.document_service()
self.generated_contents = self.generated_contents.decode('utf-8')
def test_batch_writer_is_documented(self):
self.assert_contains_lines_in_order([
'.. py:class:: DynamoDB.Table(name)',
' * :py:meth:`batch_writer()`',
' .. py:method:: batch_writer()'],
self.generated_contents
)
def test_document_interface_is_documented(self):
contents = self.get_class_document_block(
'DynamoDB.Table', self.generated_contents)
# Take an arbitrary method that uses the customization.
method_contents = self.get_method_document_block('put_item', contents)
# Make sure the request syntax is as expected.
request_syntax_contents = self.get_request_syntax_document_block(
method_contents)
self.assert_contains_lines_in_order([
' response = table.put_item(',
' Item={',
(' \'string\': \'string\'|123|Binary(b\'bytes\')'
'|True|None|set([\'string\'])|set([123])|'
'set([Binary(b\'bytes\')])|[]|{}'),
' },',
' Expected={',
' \'string\': {',
(' \'Value\': \'string\'|123'
'|Binary(b\'bytes\')|True|None|set([\'string\'])'
'|set([123])|set([Binary(b\'bytes\')])|[]|{},'),
' \'AttributeValueList\': [',
(' \'string\'|123|Binary(b\'bytes\')'
'|True|None|set([\'string\'])|set([123])|'
'set([Binary(b\'bytes\')])|[]|{},')],
request_syntax_contents)
# Make sure the response syntax is as expected.
response_syntax_contents = self.get_response_syntax_document_block(
method_contents)
self.assert_contains_lines_in_order([
' {',
' \'Attributes\': {',
(' \'string\': \'string\'|123|'
'Binary(b\'bytes\')|True|None|set([\'string\'])|'
'set([123])|set([Binary(b\'bytes\')])|[]|{}'),
' },'],
response_syntax_contents)
# Make sure the request parameter is documented correctly.
request_param_contents = self.get_request_parameter_document_block(
'Item', method_contents)
self.assert_contains_lines_in_order([
' :type Item: dict',
' :param Item: **[REQUIRED]**',
' - *(string) --*',
(' - *(valid DynamoDB type) --* - The value of the '
'attribute. The valid value types are listed in the '
':ref:`DynamoDB Reference Guide<ref_valid_dynamodb_types>`.')],
request_param_contents
)
# Make sure the response parameter is documented correctly.
response_param_contents = self.get_response_parameter_document_block(
'Attributes', method_contents)
self.assert_contains_lines_in_order([
' - **Attributes** *(dict) --*',
' - *(string) --*',
(' - *(valid DynamoDB type) --* - The value of '
'the attribute. The valid value types are listed in the '
':ref:`DynamoDB Reference Guide<ref_valid_dynamodb_types>`.')],
response_param_contents)
def test_conditions_is_documented(self):
contents = self.get_class_document_block(
'DynamoDB.Table', self.generated_contents)
# Take an arbitrary method that uses the customization.
method_contents = self.get_method_document_block('query', contents)
# Make sure the request syntax is as expected.
request_syntax_contents = self.get_request_syntax_document_block(
method_contents)
self.assert_contains_lines_in_order([
' response = table.query(',
(' FilterExpression=Attr(\'myattribute\').'
'eq(\'myvalue\'),'),
(' KeyConditionExpression=Key(\'mykey\')'
'.eq(\'myvalue\'),')],
request_syntax_contents)
# Make sure the request parameter is documented correctly.
self.assert_contains_lines_in_order([
(' :type FilterExpression: condition from '
':py:class:`boto3.dynamodb.conditions.Attr` method'),
(' :param FilterExpression: The condition(s) an '
'attribute(s) must meet. Valid conditions are listed in '
'the :ref:`DynamoDB Reference Guide<ref_dynamodb_conditions>`.'),
(' :type KeyConditionExpression: condition from '
':py:class:`boto3.dynamodb.conditions.Key` method'),
(' :param KeyConditionExpression: The condition(s) a '
'key(s) must meet. Valid conditions are listed in the '
':ref:`DynamoDB Reference Guide<ref_dynamodb_conditions>`.')],
method_contents)
def test_document_service(self):
service_documenter = ServiceDocumenter("myservice", self.session)
contents = service_documenter.document_service().decode("utf-8")
lines = [
"*********",
"MyService",
"*********",
".. contents:: Table of Contents",
" :depth: 2",
"======",
"Client",
"======",
".. py:class:: MyService.Client",
" These are the available methods:",
" * :py:meth:`sample_operation`",
"==========",
"Paginators",
"==========",
"The available paginators are:",
"* :py:class:`MyService.Paginator.SampleOperation`",
".. py:class:: MyService.Paginator.SampleOperation",
" .. py:method:: paginate(**kwargs)",
"=======",
"Waiters",
"=======",
"The available waiters are:",
"* :py:class:`MyService.Waiter.SampleOperationComplete`",
".. py:class:: MyService.Waiter.SampleOperationComplete",
" .. py:method:: wait(**kwargs)",
"================",
"Service Resource",
"================",
".. py:class:: MyService.ServiceResource()",
" These are the resource's available actions:",
" * :py:meth:`sample_operation()`",
" These are the resource's available sub-resources:",
" * :py:meth:`Sample()`",
" These are the resource's available collections:",
" * :py:attr:`samples`",
" .. py:method:: sample_operation(**kwargs)",
" .. py:method:: Sample(name)",
" .. py:attribute:: samples",
" .. py:method:: all()",
" .. py:method:: filter(**kwargs)",
" .. py:method:: limit(**kwargs)",
" .. py:method:: page_size(**kwargs)",
"======",
"Sample",
"======",
".. py:class:: MyService.Sample(name)",
" These are the resource's available identifiers:",
" * :py:attr:`name`",
" These are the resource's available attributes:",
" * :py:attr:`bar`",
" * :py:attr:`foo`",
" These are the resource's available actions:",
" * :py:meth:`load()`",
" * :py:meth:`operate()`",
" * :py:meth:`reload()`",
" These are the resource's available waiters:",
" * :py:meth:`wait_until_complete()`",
" .. py:attribute:: name",
" .. py:attribute:: bar",
" .. py:attribute:: foo",
" .. py:method:: load()",
" .. py:method:: operate(**kwargs)",
" .. py:method:: reload()",
" .. py:method:: wait_until_complete(**kwargs)",
]
self.assert_contains_lines_in_order(lines, contents)
def test_document_service_no_resource(self):
os.remove(self.resource_model_file)
service_documenter = ServiceDocumenter("myservice", self.session)
contents = service_documenter.document_service().decode("utf-8")
self.assertNotIn("Service Resource", contents)
class TestDynamoDBCustomizations(BaseDocsFunctionalTests):
def setUp(self):
self.documenter = ServiceDocumenter("dynamodb", session=Session(region_name="us-east-1"))
self.generated_contents = self.documenter.document_service()
self.generated_contents = self.generated_contents.decode("utf-8")
def test_batch_writer_is_documented(self):
self.assert_contains_lines_in_order(
[
".. py:class:: DynamoDB.Table(name)",
" * :py:meth:`batch_writer()`",
" .. py:method:: batch_writer()",
],
self.generated_contents,
)
def test_document_interface_is_documented(self):
contents = self.get_class_document_block("DynamoDB.Table", self.generated_contents)
# Take an arbitrary method that uses the customization.
method_contents = self.get_method_document_block("put_item", contents)
# Make sure the request syntax is as expected.
request_syntax_contents = self.get_request_syntax_document_block(method_contents)
self.assert_contains_lines_in_order(
[
" response = table.put_item(",
" Item={",
(
" 'string': 'string'|123|Binary(b'bytes')"
"|True|None|set(['string'])|set([123])|"
"set([Binary(b'bytes')])|[]|{}"
),
" },",
" Expected={",
" 'string': {",
(
" 'Value': 'string'|123"
"|Binary(b'bytes')|True|None|set(['string'])"
"|set([123])|set([Binary(b'bytes')])|[]|{},"
),
" 'AttributeValueList': [",
(
" 'string'|123|Binary(b'bytes')"
"|True|None|set(['string'])|set([123])|"
"set([Binary(b'bytes')])|[]|{},"
),
],
request_syntax_contents,
)
# Make sure the response syntax is as expected.
response_syntax_contents = self.get_response_syntax_document_block(method_contents)
self.assert_contains_lines_in_order(
[
" {",
" 'Attributes': {",
(
" 'string': 'string'|123|"
"Binary(b'bytes')|True|None|set(['string'])|"
"set([123])|set([Binary(b'bytes')])|[]|{}"
),
" },",
],
response_syntax_contents,
)
# Make sure the request parameter is documented correctly.
request_param_contents = self.get_request_parameter_document_block("Item", method_contents)
self.assert_contains_lines_in_order(
[
" :type Item: dict",
" :param Item: **[REQUIRED]**",
" - *(string) --*",
(
" - *(valid DynamoDB type) --* - The value of the "
"attribute. The valid value types are listed in the "
":ref:`DynamoDB Reference Guide<ref_valid_dynamodb_types>`."
),
],
request_param_contents,
)
# Make sure the response parameter is documented correctly.
response_param_contents = self.get_response_parameter_document_block("Attributes", method_contents)
self.assert_contains_lines_in_order(
[
" - **Attributes** *(dict) --*",
" - *(string) --*",
(
" - *(valid DynamoDB type) --* - The value of "
"the attribute. The valid value types are listed in the "
":ref:`DynamoDB Reference Guide<ref_valid_dynamodb_types>`."
),
],
response_param_contents,
)
def test_conditions_is_documented(self):
contents = self.get_class_document_block("DynamoDB.Table", self.generated_contents)
# Take an arbitrary method that uses the customization.
method_contents = self.get_method_document_block("query", contents)
# Make sure the request syntax is as expected.
request_syntax_contents = self.get_request_syntax_document_block(method_contents)
self.assert_contains_lines_in_order(
[
" response = table.query(",
(" FilterExpression=Attr('myattribute')." "eq('myvalue'),"),
(" KeyConditionExpression=Key('mykey')" ".eq('myvalue'),"),
],
request_syntax_contents,
)
# Make sure the request parameter is documented correctly.
self.assert_contains_lines_in_order(
[
(" :type FilterExpression: condition from " ":py:class:`boto3.dynamodb.conditions.Attr` method"),
(
" :param FilterExpression: The condition(s) an "
"attribute(s) must meet. Valid conditions are listed in "
"the :ref:`DynamoDB Reference Guide<ref_dynamodb_conditions>`."
),
(
" :type KeyConditionExpression: condition from "
":py:class:`boto3.dynamodb.conditions.Key` method"
),
(
" :param KeyConditionExpression: The condition(s) a "
"key(s) must meet. Valid conditions are listed in the "
":ref:`DynamoDB Reference Guide<ref_dynamodb_conditions>`."
),
],
method_contents,
)
class TestDynamoDBCustomizations(BaseDocsFunctionalTests):
def setUp(self):
self.documenter = ServiceDocumenter(
'dynamodb', session=Session(region_name='us-east-1'))
self.generated_contents = self.documenter.document_service()
self.generated_contents = self.generated_contents.decode('utf-8')
def test_batch_writer_is_documented(self):
self.assert_contains_lines_in_order([
'.. py:class:: DynamoDB.Table(name)',
' * :py:meth:`batch_writer()`',
' .. py:method:: batch_writer()'
], self.generated_contents)
def test_document_interface_is_documented(self):
contents = self.get_class_document_block('DynamoDB.Table',
self.generated_contents)
# Take an arbitrary method that uses the customization.
method_contents = self.get_method_document_block('put_item', contents)
# Make sure the request syntax is as expected.
request_syntax_contents = self.get_request_syntax_document_block(
method_contents)
self.assert_contains_lines_in_order([
'response = table.put_item(', 'Item={',
('\'string\': \'string\'|123|Binary(b\'bytes\')'
'|True|None|set([\'string\'])|set([123])|'
'set([Binary(b\'bytes\')])|[]|{}'), '},', 'Expected={',
'\'string\': {',
('\'Value\': \'string\'|123'
'|Binary(b\'bytes\')|True|None|set([\'string\'])'
'|set([123])|set([Binary(b\'bytes\')])|[]|{},'),
'\'AttributeValueList\': [',
('\'string\'|123|Binary(b\'bytes\')'
'|True|None|set([\'string\'])|set([123])|'
'set([Binary(b\'bytes\')])|[]|{},')
], request_syntax_contents)
# Make sure the response syntax is as expected.
response_syntax_contents = self.get_response_syntax_document_block(
method_contents)
self.assert_contains_lines_in_order([
'{', '\'Attributes\': {',
('\'string\': \'string\'|123|'
'Binary(b\'bytes\')|True|None|set([\'string\'])|'
'set([123])|set([Binary(b\'bytes\')])|[]|{}'), '},'
], response_syntax_contents)
# Make sure the request parameter is documented correctly.
request_param_contents = self.get_request_parameter_document_block(
'Item', method_contents)
self.assert_contains_lines_in_order([
':type Item: dict', ':param Item: **[REQUIRED]**',
'- *(string) --*',
('- *(valid DynamoDB type) --* - The value of the '
'attribute. The valid value types are listed in the '
':ref:`DynamoDB Reference Guide<ref_valid_dynamodb_types>`.')
], request_param_contents)
# Make sure the response parameter is documented correctly.
response_param_contents = self.get_response_parameter_document_block(
'Attributes', method_contents)
self.assert_contains_lines_in_order([
'- **Attributes** *(dict) --*', '- *(string) --*',
('- *(valid DynamoDB type) --* - The value of '
'the attribute. The valid value types are listed in the '
':ref:`DynamoDB Reference Guide<ref_valid_dynamodb_types>`.')
], response_param_contents)
def test_conditions_is_documented(self):
contents = self.get_class_document_block('DynamoDB.Table',
self.generated_contents)
# Take an arbitrary method that uses the customization.
method_contents = self.get_method_document_block('query', contents)
# Make sure the request syntax is as expected.
request_syntax_contents = self.get_request_syntax_document_block(
method_contents)
self.assert_contains_lines_in_order([
'response = table.query(',
('FilterExpression=Attr(\'myattribute\').'
'eq(\'myvalue\'),'),
('KeyConditionExpression=Key(\'mykey\')'
'.eq(\'myvalue\'),')
], request_syntax_contents)
# Make sure the request parameter is documented correctly.
self.assert_contains_lines_in_order(
[(':type FilterExpression: condition from '
':py:class:`boto3.dynamodb.conditions.Attr` method'),
(':param FilterExpression: The condition(s) an '
'attribute(s) must meet. Valid conditions are listed in '
'the :ref:`DynamoDB Reference Guide<ref_dynamodb_conditions>`.'),
(':type KeyConditionExpression: condition from '
':py:class:`boto3.dynamodb.conditions.Key` method'),
(':param KeyConditionExpression: The condition(s) a '
'key(s) must meet. Valid conditions are listed in the '
':ref:`DynamoDB Reference Guide<ref_dynamodb_conditions>`.')],
method_contents)
def test_document_service_no_resource(self):
os.remove(self.resource_model_file)
service_documenter = ServiceDocumenter('myservice', self.session)
contents = service_documenter.document_service().decode('utf-8')
self.assertNotIn('Service Resource', contents)
def test_document_service(self):
service_documenter = ServiceDocumenter('myservice', self.session)
contents = service_documenter.document_service().decode('utf-8')
lines = [
'*********',
'MyService',
'*********',
'.. contents:: Table of Contents',
' :depth: 2',
'======',
'Client',
'======',
'.. py:class:: MyService.Client',
' These are the available methods:',
' * :py:meth:`~MyService.Client.sample_operation`',
' **Examples** ',
' Sample Description.',
' ::',
' response = client.sample_operation(',
'==========',
'Paginators',
'==========',
'The available paginators are:',
'* :py:class:`MyService.Paginator.SampleOperation`',
'.. py:class:: MyService.Paginator.SampleOperation',
' .. py:method:: paginate(**kwargs)',
'=======',
'Waiters',
'=======',
'The available waiters are:',
'* :py:class:`MyService.Waiter.SampleOperationComplete`',
'.. py:class:: MyService.Waiter.SampleOperationComplete',
' .. py:method:: wait(**kwargs)',
'================',
'Service Resource',
'================',
'.. py:class:: MyService.ServiceResource()',
" These are the resource's available actions:",
' * :py:meth:`sample_operation()`',
" These are the resource's available sub-resources:",
' * :py:meth:`Sample()`',
" These are the resource's available collections:",
' * :py:attr:`samples`',
' .. py:method:: sample_operation(**kwargs)',
' .. py:method:: Sample(name)',
' .. py:attribute:: samples',
' .. py:method:: all()',
' .. py:method:: filter(**kwargs)',
' .. py:method:: limit(**kwargs)',
' .. py:method:: page_size(**kwargs)',
'======',
'Sample',
'======',
'.. py:class:: MyService.Sample(name)',
" These are the resource's available identifiers:",
' * :py:attr:`name`',
" These are the resource's available attributes:",
' * :py:attr:`bar`',
' * :py:attr:`foo`',
" These are the resource's available actions:",
' * :py:meth:`load()`',
' * :py:meth:`operate()`',
' * :py:meth:`reload()`',
" These are the resource's available waiters:",
' * :py:meth:`wait_until_complete()`',
' .. py:attribute:: name',
' .. py:attribute:: bar',
' .. py:attribute:: foo',
' .. py:method:: load()',
' .. py:method:: operate(**kwargs)',
' .. py:method:: reload()',
' .. py:method:: wait_until_complete(**kwargs)',
]
self.assert_contains_lines_in_order(lines, contents)
def test_document_service_no_resource(self):
os.remove(self.resource_model_file)
service_documenter = ServiceDocumenter('myservice', self.session)
contents = service_documenter.document_service().decode('utf-8')
self.assertNotIn('Service Resource', contents)
def test_document_service(self):
service_documenter = ServiceDocumenter('myservice', self.session)
contents = service_documenter.document_service().decode('utf-8')
lines = [
'*********',
'MyService',
'*********',
'.. contents:: Table of Contents',
' :depth: 2',
'======',
'Client',
'======',
'.. py:class:: MyService.Client',
' These are the available methods:',
' * :py:meth:`sample_operation`',
'==========',
'Paginators',
'==========',
'The available paginators are:',
'* :py:class:`MyService.Paginator.SampleOperation`',
'.. py:class:: MyService.Paginator.SampleOperation',
' .. py:method:: paginate(**kwargs)',
'=======',
'Waiters',
'=======',
'The available waiters are:',
'* :py:class:`MyService.Waiter.SampleOperationComplete`',
'.. py:class:: MyService.Waiter.SampleOperationComplete',
' .. py:method:: wait(**kwargs)',
'================',
'Service Resource',
'================',
'.. py:class:: MyService.ServiceResource()',
" These are the resource's available actions:",
' * :py:meth:`sample_operation()`',
" These are the resource's available sub-resources:",
' * :py:meth:`Sample()`',
" These are the resource's available collections:",
' * :py:attr:`samples`',
' .. py:method:: sample_operation(**kwargs)',
' .. py:method:: Sample(name)',
' .. py:attribute:: samples',
' .. py:method:: all()',
' .. py:method:: filter(**kwargs)',
' .. py:method:: limit(**kwargs)',
' .. py:method:: page_size(**kwargs)',
'======',
'Sample',
'======',
'.. py:class:: MyService.Sample(name)',
" These are the resource's available identifiers:",
' * :py:attr:`name`',
" These are the resource's available attributes:",
' * :py:attr:`bar`',
' * :py:attr:`foo`',
" These are the resource's available actions:",
' * :py:meth:`load()`',
' * :py:meth:`operate()`',
' * :py:meth:`reload()`',
" These are the resource's available waiters:",
' * :py:meth:`wait_until_complete()`',
' .. py:attribute:: name',
' .. py:attribute:: bar',
' .. py:attribute:: foo',
' .. py:method:: load()',
' .. py:method:: operate(**kwargs)',
' .. py:method:: reload()',
' .. py:method:: wait_until_complete(**kwargs)',
]
self.assert_contains_lines_in_order(lines, contents)
