pydoctor.test.test_epydoc2stan

module documentation
(source)

Undocumented

Class InMemoryInventory A simple inventory implementation which has an in-memory API link mapping.
Class RecordingAnnotationLinker A DocstringLinker implementation that cannot find any links, but does record which identifiers it was asked to link.
Function docstring2html Undocumented
Function insert_break_points Undocumented
Function summary2html Undocumented
Function test_annotation_formatting Perform two checks on the annotation formatting:
Function test_CachedEpydocLinker The CachedEpydocLinker returns the same Tag object without resolving the name and re-creating the link tag all the time.
Function test_CachedEpydocLinker_same_page_optimization When _CachedEpydocLinker.same_page_optimization is True, the linker will create URLs with only the anchor if we're lnking to an object on the same page.
Function test_CachedEpydocLinker_warnings Warnings should be reported only once per invalid name per line, no matter the number of times we call summary2html() or docstring2html() or the order we call these functions.
Function test_cli_docformat_plaintext_overrides_module_docformat When System.options.docformat is set to plaintext it overwrites any specific Module.docformat defined for a module.
Function test_constant_values_rst Test epydoc2stan.format_constant_value().
Function test_constructor_param_on_class Constructor parameters can be documented on the class.
Function test_EpydocLinker_adds_intersphinx_link_css_class The EpydocLinker return a link with the CSS class 'intersphinx-link' when it's using intersphinx.
Function test_EpydocLinker_look_for_intersphinx_hit Return the link from inventory based on first package name.
Function test_EpydocLinker_look_for_intersphinx_no_link Return None if inventory had no link for our markup.
Function test_EpydocLinker_resolve_identifier_xref_internal_full_name Link to an internal object referenced by its full name.
Function test_EpydocLinker_resolve_identifier_xref_intersphinx_absolute_id Returns the link from Sphinx inventory based on a cross reference ID specified in absolute dotted path and with a custom pretty text for the URL.
Function test_EpydocLinker_resolve_identifier_xref_intersphinx_link_not_found A message is sent to stdout when no link could be found for the reference, while returning the reference name without an A link tag. The message contains the full name under which the reference was resolved...
Function test_EpydocLinker_resolve_identifier_xref_intersphinx_relative_id Return the link from inventory using short names, by resolving them based on the imports done in the module.
Function test_EpydocLinker_resolve_identifier_xref_order Check that the best match is picked when there are multiple candidates.
Function test_func_arg_and_ret_annotation Undocumented
Function test_func_arg_and_ret_annotation_with_override Undocumented
Function test_func_arg_not_inherited Do not warn when a subclass method lacks parameters that are documented in an inherited docstring.
Function test_func_arg_when_doc_missing Undocumented
Function test_func_missing_param_name Param and type fields must include the name of the parameter.
Function test_func_no_such_arg Warn about documented parameters that don't exist in the definition.
Function test_func_no_such_arg_warn_once Warn exactly once about a param/type combination not existing.
Function test_func_param_as_keyword Warn when a parameter is documented as a @keyword.
Function test_func_param_duplicate Warn when the same parameter is documented more than once.
Function test_func_raise_linked Raise fields are formatted by linking the exception type.
Function test_func_raise_missing_exception_type When a raise field is missing the exception type, a warning is logged and the HTML will list the exception type as unknown.
Function test_func_starargs Var-args can be named in fields with or without asterixes. Constructor parameters can be documented on the class.
Function test_func_starargs_more Star arguments, even if there are not named 'args' or 'kwargs', are recognized.
Function test_func_starargs_no_docstring Star arguments, even if there are not docstring attached, will be rendered with stars.
Function test_func_undocumented_return_nothing When the returned value is undocumented (no 'return' field) and its type annotation is None, omit the "Returns" entry from the output.
Function test_func_undocumented_return_something When the returned value is undocumented (no 'return' field) and its type annotation is not None, include the "Returns" entry in the output.
Function test_html_empty_module Undocumented
Function test_inline_field_name Warn if a name is given for a type field in a variable docstring. A variable docstring only documents a single variable, so the name is redundant at best and misleading at worst.
Function test_inline_field_type The type field in a variable docstring updates the parsed_type of the Attribute it documents.
Function test_insert_break_points_camel_case Undocumented
Function test_insert_break_points_dotted_name Undocumented
Function test_insert_break_points_identity No break points are introduced for values containing a single world.
Function test_insert_break_points_snake_case Undocumented
Function test_ivar_overriding_attribute An 'ivar' field in a subclass overrides a docstring for the same attribute set in the base class.
Function test_missing_field_name Undocumented
Function test_missing_param_computed_base Do not warn if a parameter might be added by a computed base class.
Function test_module_docformat Test if Module.docformat effectively override System.options.docformat
Function test_module_docformat_inheritence Undocumented
Function test_module_docformat_with_docstring_inheritence Undocumented
Function test_multiple_types Undocumented
Function test_self_cls_in_function_params 'self' and 'cls' in parameter table of regular function should appear because we don't know if it's a badly named argument OR it's actually assigned to a legit class/instance method outside of the class scope: https://github...
Function test_stem_identifier Undocumented
Function test_summary Undocumented
Function test_TestCachedEpydocLinker A test case for the testing linker _TestCachedEpydocLinker. The test linker is initialized with a maximum number of non-cached requests it can make and an AssertionError is raised if it makes too many requests.
Function test_unexpected_field_args Warn when field arguments that should be empty aren't.
Function test_unknown_field_name Undocumented
Function test_warns_field Test if the :warns: field is correctly recognized.
Function test_xref_link_intersphinx A linked name that is documented in another project is linked using an absolute URL (retrieved via Intersphinx).
Function test_xref_link_not_found A linked name that is not found is output as text.
Function test_xref_link_other_page A linked name that is documented on a different page but within the same project is linked using a relative URL.
Function test_xref_link_same_page A linked name that is documented on the same page is linked using only a fragment as the URL. But that does not happend in summaries.
Function test_xref_not_found_epytext When a link in an epytext docstring cannot be resolved, the reference and the line number of the link should be reported.
Function test_xref_not_found_restructured When a link in an reStructedText docstring cannot be resolved, the reference and the line number of the link should be reported.
Function test_xref_not_found_restructured_in_para When an invalid link is in the middle of a paragraph, we still report the right line number.
Function test_yields_field Test if the :warns: field is correctly recognized.
Class _TestCachedEpydocLinker Docstring linker for testing the caching of results.
def docstring2html(obj, docformat=None): (source)

Undocumented

Parameters
obj:model.DocumentableUndocumented
docformat:Optional[str]Undocumented
Returns
strUndocumented
def insert_break_points(t): (source)

Undocumented

Parameters
t:strUndocumented
Returns
strUndocumented
def summary2html(obj): (source)

Undocumented

Parameters
obj:model.DocumentableUndocumented
Returns
strUndocumented
@mark.parametrize('annotation', ('<bool>', '<NotImplemented>', '<typing.Iterable>[<int>]', '<Literal>[<True>]', '<Mapping>[<str>, <C>]', '<Tuple>[<a.b.C>, <int>]', '<Tuple>[<a.b.C>, ...]', '<Callable>[[<str>, <bool>], <None>]'))
def test_annotation_formatting(annotation): (source)

Perform two checks on the annotation formatting:

  • all type names in the annotation are passed to the linker
  • the plain text version of the output matches the input
Parameters
annotation:strUndocumented
Note
The annotation formatting is now handled by PyvalColorizer. We use the function flatten_text in order to back reproduce the original text annotations.
def test_CachedEpydocLinker(): (source)

The CachedEpydocLinker returns the same Tag object without resolving the name and re-creating the link tag all the time.

def test_CachedEpydocLinker_same_page_optimization(): (source)

When _CachedEpydocLinker.same_page_optimization is True, the linker will create URLs with only the anchor if we're lnking to an object on the same page.

Otherwise it will always use return a URL with a filename, this is used to generate the summaries.

def test_CachedEpydocLinker_warnings(capsys): (source)

Warnings should be reported only once per invalid name per line, no matter the number of times we call summary2html() or docstring2html() or the order we call these functions.

Parameters
capsys:CapSysUndocumented
def test_cli_docformat_plaintext_overrides_module_docformat(capsys): (source)

When System.options.docformat is set to plaintext it overwrites any specific Module.docformat defined for a module.

See https://github.com/twisted/pydoctor/issues/503 for the reason of this behavior.

Parameters
capsys:CapSysUndocumented
def test_constant_values_rst(capsys): (source)

Test epydoc2stan.format_constant_value().

Parameters
capsys:CapSysUndocumented
def test_constructor_param_on_class(capsys): (source)

Constructor parameters can be documented on the class.

Parameters
capsys:CapSysUndocumented
def test_EpydocLinker_adds_intersphinx_link_css_class(): (source)

The EpydocLinker return a link with the CSS class 'intersphinx-link' when it's using intersphinx.

def test_EpydocLinker_look_for_intersphinx_hit(): (source)

Return the link from inventory based on first package name.

def test_EpydocLinker_look_for_intersphinx_no_link(): (source)

Return None if inventory had no link for our markup.

def test_EpydocLinker_resolve_identifier_xref_internal_full_name(): (source)

Link to an internal object referenced by its full name.

def test_EpydocLinker_resolve_identifier_xref_intersphinx_absolute_id(): (source)

Returns the link from Sphinx inventory based on a cross reference ID specified in absolute dotted path and with a custom pretty text for the URL.

def test_EpydocLinker_resolve_identifier_xref_intersphinx_link_not_found(capsys): (source)

A message is sent to stdout when no link could be found for the reference, while returning the reference name without an A link tag. The message contains the full name under which the reference was resolved. FIXME: Use a proper logging system instead of capturing stdout. https://github.com/twisted/pydoctor/issues/112

Parameters
capsys:CapSysUndocumented
def test_EpydocLinker_resolve_identifier_xref_intersphinx_relative_id(): (source)

Return the link from inventory using short names, by resolving them based on the imports done in the module.

def test_EpydocLinker_resolve_identifier_xref_order(capsys): (source)

Check that the best match is picked when there are multiple candidates.

Parameters
capsys:CapSysUndocumented
@pytest.mark.xfail
def test_func_arg_and_ret_annotation(): (source)

Undocumented

@pytest.mark.xfail
def test_func_arg_and_ret_annotation_with_override(): (source)

Undocumented

def test_func_arg_not_inherited(capsys): (source)

Do not warn when a subclass method lacks parameters that are documented in an inherited docstring.

Parameters
capsys:CapSysUndocumented
@pytest.mark.xfail
def test_func_arg_when_doc_missing(): (source)

Undocumented

def test_func_missing_param_name(capsys): (source)

Param and type fields must include the name of the parameter.

Parameters
capsys:CapSysUndocumented
@mark.parametrize('field', ('param', 'type'))
def test_func_no_such_arg(field, capsys): (source)

Warn about documented parameters that don't exist in the definition.

Parameters
field:strUndocumented
capsys:CapSysUndocumented
def test_func_no_such_arg_warn_once(capsys): (source)

Warn exactly once about a param/type combination not existing.

Parameters
capsys:CapSysUndocumented
def test_func_param_as_keyword(capsys): (source)

Warn when a parameter is documented as a @keyword.

Parameters
capsys:CapSysUndocumented
def test_func_param_duplicate(capsys): (source)

Warn when the same parameter is documented more than once.

Parameters
capsys:CapSysUndocumented
def test_func_raise_linked(): (source)

Raise fields are formatted by linking the exception type.

def test_func_raise_missing_exception_type(capsys): (source)

When a raise field is missing the exception type, a warning is logged and the HTML will list the exception type as unknown.

Parameters
capsys:CapSysUndocumented
def test_func_starargs(capsys): (source)

Var-args can be named in fields with or without asterixes. Constructor parameters can be documented on the class.

Parameters
capsys:CapSysUndocumented
Note
Asterixes need to be escaped with reStructuredText.
def test_func_starargs_more(capsys): (source)

Star arguments, even if there are not named 'args' or 'kwargs', are recognized.

Parameters
capsys:CapSysUndocumented
def test_func_starargs_no_docstring(capsys): (source)

Star arguments, even if there are not docstring attached, will be rendered with stars.

Parameters
capsys:CapSysUndocumented
Note
This test might not pass anymore when we include the annotations inside the signatures.
def test_func_undocumented_return_nothing(): (source)

When the returned value is undocumented (no 'return' field) and its type annotation is None, omit the "Returns" entry from the output.

def test_func_undocumented_return_something(): (source)

When the returned value is undocumented (no 'return' field) and its type annotation is not None, include the "Returns" entry in the output.

def test_html_empty_module(): (source)

Undocumented

def test_inline_field_name(capsys): (source)

Warn if a name is given for a type field in a variable docstring. A variable docstring only documents a single variable, so the name is redundant at best and misleading at worst.

Parameters
capsys:CapSysUndocumented
def test_inline_field_type(capsys): (source)

The type field in a variable docstring updates the parsed_type of the Attribute it documents.

Parameters
capsys:CapSysUndocumented
def test_insert_break_points_camel_case(): (source)

Undocumented

def test_insert_break_points_dotted_name(): (source)

Undocumented

def test_insert_break_points_identity(): (source)

No break points are introduced for values containing a single world.

def test_insert_break_points_snake_case(): (source)

Undocumented

def test_ivar_overriding_attribute(): (source)

An 'ivar' field in a subclass overrides a docstring for the same attribute set in the base class.

The 'a' attribute in the test code reproduces a regression introduced in pydoctor 20.7.0, where the summary would be constructed from the base class documentation instead. The problem was in the fact that a split field's docstring is stored in 'parsed_docstring', while format_summary() looked there only if no unparsed docstring could be found.

The 'b' attribute in the test code is there to make sure that in the absence of an 'ivar' field, the docstring is inherited.

def test_missing_field_name(capsys): (source)

Undocumented

Parameters
capsys:CapSysUndocumented
def test_missing_param_computed_base(capsys): (source)

Do not warn if a parameter might be added by a computed base class.

Parameters
capsys:CapSysUndocumented
def test_module_docformat(capsys): (source)

Test if Module.docformat effectively override System.options.docformat

Parameters
capsys:CapSysUndocumented
def test_module_docformat_inheritence(capsys): (source)

Undocumented

Parameters
capsys:CapSysUndocumented
def test_module_docformat_with_docstring_inheritence(capsys): (source)

Undocumented

Parameters
capsys:CapSysUndocumented
def test_multiple_types(): (source)

Undocumented

def test_self_cls_in_function_params(capsys): (source)

'self' and 'cls' in parameter table of regular function should appear because we don't know if it's a badly named argument OR it's actually assigned to a legit class/instance method outside of the class scope: https://github.com/twisted/pydoctor/issues/13

Until issue #13 is fixed (which is not so easy), the safe side is to show them.

Parameters
capsys:CapSysUndocumented
def test_stem_identifier(): (source)

Undocumented

def test_summary(): (source)

Undocumented

def test_TestCachedEpydocLinker(): (source)

A test case for the testing linker _TestCachedEpydocLinker. The test linker is initialized with a maximum number of non-cached requests it can make and an AssertionError is raised if it makes too many requests.

def test_unexpected_field_args(capsys): (source)

Warn when field arguments that should be empty aren't.

Parameters
capsys:CapSysUndocumented
def test_unknown_field_name(capsys): (source)

Undocumented

Parameters
capsys:CapSysUndocumented
def test_warns_field(capsys): (source)

Test if the :warns: field is correctly recognized.

Parameters
capsys:CapSysUndocumented
def test_xref_link_intersphinx(): (source)

A linked name that is documented in another project is linked using an absolute URL (retrieved via Intersphinx).

def test_xref_link_not_found(): (source)

A linked name that is not found is output as text.

def test_xref_link_other_page(): (source)

A linked name that is documented on a different page but within the same project is linked using a relative URL.

def test_xref_link_same_page(): (source)

A linked name that is documented on the same page is linked using only a fragment as the URL. But that does not happend in summaries.

def test_xref_not_found_epytext(capsys): (source)

When a link in an epytext docstring cannot be resolved, the reference and the line number of the link should be reported.

Parameters
capsys:CapSysUndocumented
def test_xref_not_found_restructured(capsys): (source)

When a link in an reStructedText docstring cannot be resolved, the reference and the line number of the link should be reported.

Parameters
capsys:CapSysUndocumented
def test_xref_not_found_restructured_in_para(capsys): (source)

When an invalid link is in the middle of a paragraph, we still report the right line number.

Parameters
capsys:CapSysUndocumented
def test_yields_field(capsys): (source)

Test if the :warns: field is correctly recognized.

Parameters
capsys:CapSysUndocumented