def test_loading_pydantic_model():
"""Handle Pydantic models."""
loader = Loader()
obj = loader.get_object_documentation("tests.fixtures.pydantic.Person")
assert obj.docstring == "Simple Pydantic Model for a person's information"
assert "pydantic" in obj.properties
assert len(obj.attributes) == 2
name_attr = next(attr for attr in obj.attributes if attr.name == "name")
assert name_attr.type == str
assert name_attr.docstring == "The person's name"
assert "pydantic" in name_attr.properties
age_attr = next(attr for attr in obj.attributes if attr.name == "age")
assert age_attr.type == int
assert age_attr.docstring == "The person's age which must be at minimum 18"
assert "pydantic" in age_attr.properties
def test_loading_marshmallow_model():
"""Handle Marshmallow models."""
loader = Loader()
obj = loader.get_object_documentation("tests.fixtures.marshmallow.Person")
assert obj.docstring == "Simple Marshmallow Model for a person's information"
assert "marshmallow-model" in obj.properties
name_attr = next(attr for attr in obj.attributes if attr.name == "name")
assert name_attr.type == fields.Str
assert name_attr.docstring == "The person's name"
assert "marshmallow-field" in name_attr.properties
assert "required" in name_attr.properties
age_attr = next(attr for attr in obj.attributes if attr.name == "age")
assert age_attr.type == fields.Int
assert age_attr.docstring == "The person's age which must be at minimum 18"
assert "marshmallow-field" in age_attr.properties
def test_parse_module_attributes_section():
"""Parse attributes section in modules."""
loader = Loader()
obj = loader.get_object_documentation("tests.fixtures.docstring_attributes_section")
assert len(obj.docstring_sections) == 2
assert not obj.docstring_errors
attr_section = obj.docstring_sections[1]
assert attr_section.type == Section.Type.ATTRIBUTES
assert len(attr_section.value) == 5
expected = [
{"name": "A", "annotation": "int", "description": "Alpha."},
{"name": "B", "annotation": "bytes", "description": "Beta."},
{"name": "C", "annotation": "bool", "description": "Gamma."},
{"name": "D", "annotation": "", "description": "Delta."},
{"name": "E", "annotation": "float", "description": "Epsilon."},
]
assert [serialize_attribute(attr) for attr in attr_section.value] == expected
def test_loading_pydantic_model():
"""Handle Pydantic models."""
loader = Loader()
obj = loader.get_object_documentation("tests.fixtures.pydantic.Person")
assert obj.docstring == "Simple Pydantic Model for a person's information"
assert "pydantic-model" in obj.properties
name_attr = next(attr for attr in obj.attributes if attr.name == "name")
assert name_attr.type == str
assert name_attr.docstring == "The person's name"
assert "pydantic-field" in name_attr.properties
age_attr = next(attr for attr in obj.attributes if attr.name == "age")
assert age_attr.type == int
assert age_attr.docstring == "The person's age which must be at minimum 18"
assert "pydantic-field" in age_attr.properties
labels_attr = next(attr for attr in obj.attributes
if attr.name == "labels")
assert labels_attr.type == Set[str]
assert labels_attr.docstring == "Set of labels the person can be referred by"
assert "pydantic-field" in labels_attr.properties
def test_loading_coroutine():
"""Load documentation for a coroutine."""
loader = Loader()
obj = loader.get_object_documentation(
"tests.fixtures.asyncio.coroutine_function")
assert "async" in obj.properties
def test_loading_wrapped_function():
"""Load documentation for wrapped function, not wrapper."""
loader = Loader()
obj = loader.get_object_documentation(
"tests.fixtures.wrapped_objects.my_function")
assert obj.docstring == "My docstring."
def test_loading_no_members():
"""Select no members."""
loader = Loader()
obj = loader.get_object_documentation(
"tests.fixtures.the_package.the_module", members=False)
assert not obj.children
def test_loading_function():
"""Select function."""
loader = Loader()
obj = loader.get_object_documentation(
"tests.fixtures.the_package.the_module.the_function")
assert obj.docstring == "The function docstring."
def test_loading_classmethod():
"""Select class method."""
loader = Loader()
obj = loader.get_object_documentation(
"tests.fixtures.the_package.the_module.TheClass.the_class_method")
assert obj.docstring == "The class method docstring."
def test_loading_inherited_members():
"""Select inherited members."""
loader = Loader(inherited_members=True)
obj = loader.get_object_documentation("tests.fixtures.inherited_members.Child")
for child_name in ("method1", "method2", "V1", "V2"):
assert child_name in (child.name for child in obj.children)
def test_loading_with_filters_reselection():
"""A filter can cancel a previous filter."""
loader = Loader(filters=["![A-Z_]", "[a-z]"])
obj = loader.get_object_documentation("tests.fixtures.the_package.the_module")
assert obj.classes
assert obj.classes[0].name == "TheClass"
def test_loading_with_filters():
"""Select with filters."""
loader = Loader(filters=["!^[A-Z_]+$"])
obj = loader.get_object_documentation("tests.fixtures.the_package.the_module")
for child in obj.children:
assert child.name != "THE_ATTRIBUTE"
def test_loading_explicit_members():
"""Select members explicitly."""
loader = Loader()
obj = loader.get_object_documentation("tests.fixtures.the_package.the_module", members={"TheClass"})
assert len(obj.children) == 1
assert obj.children[0].name == "TheClass"
def test_loading_cython_attribute():
"""Select cython attribute."""
loader = Loader()
obj = loader.get_object_documentation(
"tests.fixtures.cython.module_attribute")
assert obj.docstring == "The module attribute docstring."
def test_loading_attribute_from_module_docs():
"""Select attribute from module docs."""
loader = Loader()
obj = loader.get_object_documentation(
"tests.fixtures.docstring_attributes_section.A")
assert obj.docstring == "Alpha."
def test_loading_class():
"""Handle classes."""
loader = Loader()
obj = loader.get_object_documentation(
"tests.fixtures.the_package.the_module.TheClass")
assert obj.docstring == "The class docstring."
def test_loading_class_with_multiline_docstring_starting_on_first_line():
"""Handle classes with multiline docstrings where the first line is next to the triple-quotes."""
loader = Loader()
obj = loader.get_object_documentation(
"tests.fixtures.first_line_class_docstring.TheClass")
assert obj.docstring == """The first line of the docstring.\n\nA bit more of the docstring."""
def test_loading_selected_inherited_members():
"""Select specific members, some of them being inherited."""
loader = Loader(inherited_members=True)
obj = loader.get_object_documentation("tests.fixtures.inherited_members.Child", members={"V1", "V2"})
for child_name in ("V1", "V2"):
assert child_name in (child.name for child in obj.children)
def test_loading_nested_class():
"""Select nested class."""
loader = Loader()
obj = loader.get_object_documentation(
"tests.fixtures.the_package.the_module.TheClass.TheNestedClass")
assert obj.docstring == "The nested class docstring."
def test_loading_pydantic_inherited_members():
"""Select inherited members in Pydantic models."""
loader = Loader(inherited_members=True)
obj = loader.get_object_documentation("tests.fixtures.inherited_members.ChildModel")
for child_name in ("a", "b"):
assert child_name in (child.name for child in obj.children)
def test_loading_writable_property():
"""Select writable property."""
loader = Loader()
obj = loader.get_object_documentation(
"tests.fixtures.the_package.the_module.TheClass.the_writable_property")
assert obj.docstring == "The writable property getter docstring."
def test_loading_module_wrapped_members():
"""Load documentation for wrapped function, not wrapper."""
loader = Loader()
obj = loader.get_object_documentation("tests.fixtures.wrapped_objects")
assert obj.functions and obj.functions[0].docstring == "My docstring."
assert obj.classes and obj.classes[0].methods and obj.classes[0].methods[0].docstring == "Hello!"
def test_loading_attribute():
"""Select attribute."""
loader = Loader()
obj = loader.get_object_documentation(
"tests.fixtures.the_package.the_module.THE_ATTRIBUTE")
assert obj.docstring == "The attribute docstring."
def test_loading_deep_package():
"""Handle deep nesting of packages."""
loader = Loader()
obj = loader.get_object_documentation("tests.fixtures.pkg1.pkg2.pkg3.pkg4.pkg5")
assert obj.docstring == "Hello from the abyss."
assert obj.path == "tests.fixtures.pkg1.pkg2.pkg3.pkg4.pkg5"
def test_not_loading_pydantic_inherited_members():
"""Do not select inherited members in Pydantic models."""
loader = Loader(inherited_members=False)
obj = loader.get_object_documentation(
"tests.fixtures.inherited_members.ChildModel")
assert "a" not in (child.name for child in obj.children)
def test_inheriting_enum_Enum():
"""Handle `enum.Enum` classes."""
"""See details at [tests.fixtures.inheriting_enum_Enum][]."""
loader = Loader()
loader.get_object_documentation("tests.fixtures.inheriting_enum_Enum")
assert not loader.errors
def test_unwrap_object_with_getattr_method_raising_exception():
"""Try loading an object that defines a `__getattr__` method which raises an exception."""
loader = Loader()
loader.get_object_documentation("tests.fixtures.unwrap_getattr_raises")
def test_loading_package():
"""Handle basic packages."""
loader = Loader()
obj = loader.get_object_documentation("tests.fixtures.the_package")
assert obj.docstring == "The package docstring."
def test_loading_method_without_async_property():
"""Load documentation for a method that is not a coroutine."""
loader = Loader()
obj = loader.get_object_documentation(
"tests.fixtures.the_package.the_module.TheClass.the_method")
assert "async" not in obj.properties
def test_loading_module():
"""Handle single modules."""
loader = Loader()
obj = loader.get_object_documentation(
"tests.fixtures.the_package.the_module")
assert obj.docstring == "The module docstring."
