Skip to content

inventory ¤

Module responsible for the objects inventory.

Classes:

Inventory ¤

Inventory(
    items: list[InventoryItem] | None = None,
    project: str = "project",
    version: str = "0.0.0",
)

Bases: dict

Inventory of collected and rendered objects.

Parameters:

  • items (list[InventoryItem] | None, default: None ) –

    A list of items.

  • project (str, default: 'project' ) –

    The project name.

  • version (str, default: '0.0.0' ) –

    The project version.

Methods:

  • format_sphinx –

    Format this inventory as a Sphinx objects.inv file.

  • parse_sphinx –

    Parse a Sphinx v2 inventory file and return an Inventory from it.

  • register –

    Create and register an item.

Source code in src/mkdocstrings/inventory.py 
76
77
78
79
80
81
82
83
84
85
86
87
88
89
def __init__(self, items: list[InventoryItem] | None = None, project: str = "project", version: str = "0.0.0"):
    """Initialize the object.

    Arguments:
        items: A list of items.
        project: The project name.
        version: The project version.
    """
    super().__init__()
    items = items or []
    for item in items:
        self[item.name] = item
    self.project = project
    self.version = version

format_sphinx ¤

format_sphinx() -> bytes

Format this inventory as a Sphinx objects.inv file.

Returns:

  • bytes –

    The inventory as bytes.

Source code in src/mkdocstrings/inventory.py 
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
def format_sphinx(self) -> bytes:
    """Format this inventory as a Sphinx `objects.inv` file.

    Returns:
        The inventory as bytes.
    """
    header = (
        dedent(
            f"""
            # Sphinx inventory version 2
            # Project: {self.project}
            # Version: {self.version}
            # The remainder of this file is compressed using zlib.
            """,
        )
        .lstrip()
        .encode("utf8")
    )

    lines = [
        item.format_sphinx().encode("utf8")
        for item in sorted(self.values(), key=lambda item: (item.domain, item.name))
    ]
    return header + zlib.compress(b"\n".join(lines) + b"\n", 9)

parse_sphinx classmethod ¤

parse_sphinx(
    in_file: BinaryIO,
    *,
    domain_filter: Collection[str] = ()
) -> Inventory

Parse a Sphinx v2 inventory file and return an Inventory from it.

Parameters:

  • in_file (BinaryIO) –

    The binary file-like object to read from.

  • domain_filter (Collection[str], default: () ) –

    A collection of domain values to allow (and filter out all other ones).

Returns:

  • Inventory –

    An inventory containing the collected items.

Source code in src/mkdocstrings/inventory.py 
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
@classmethod
def parse_sphinx(cls, in_file: BinaryIO, *, domain_filter: Collection[str] = ()) -> Inventory:
    """Parse a Sphinx v2 inventory file and return an `Inventory` from it.

    Arguments:
        in_file: The binary file-like object to read from.
        domain_filter: A collection of domain values to allow (and filter out all other ones).

    Returns:
        An inventory containing the collected items.
    """
    for _ in range(4):
        in_file.readline()
    lines = zlib.decompress(in_file.read()).splitlines()
    items = [InventoryItem.parse_sphinx(line.decode("utf8")) for line in lines]
    if domain_filter:
        items = [item for item in items if item.domain in domain_filter]
    return cls(items)

register ¤

register(
    name: str,
    domain: str,
    role: str,
    uri: str,
    priority: int = 1,
    dispname: str | None = None,
) -> None

Create and register an item.

Parameters:

  • name (str) –

    The item name.

  • domain (str) –

    The item domain, like 'python' or 'crystal'.

  • role (str) –

    The item role, like 'class' or 'method'.

  • uri (str) –

    The item URI.

  • priority (int, default: 1 ) –

    The item priority. Only used internally by mkdocstrings and Sphinx.

  • dispname (str | None, default: None ) –

    The item display name.

Source code in src/mkdocstrings/inventory.py 
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
def register(
    self,
    name: str,
    domain: str,
    role: str,
    uri: str,
    priority: int = 1,
    dispname: str | None = None,
) -> None:
    """Create and register an item.

    Arguments:
        name: The item name.
        domain: The item domain, like 'python' or 'crystal'.
        role: The item role, like 'class' or 'method'.
        uri: The item URI.
        priority: The item priority. Only used internally by mkdocstrings and Sphinx.
        dispname: The item display name.
    """
    self[name] = InventoryItem(
        name=name,
        domain=domain,
        role=role,
        uri=uri,
        priority=priority,
        dispname=dispname,
    )

InventoryItem ¤

InventoryItem(
    name: str,
    domain: str,
    role: str,
    uri: str,
    priority: int = 1,
    dispname: str | None = None,
)

Inventory item.

Parameters:

  • name (str) –

    The item name.

  • domain (str) –

    The item domain, like 'python' or 'crystal'.

  • role (str) –

    The item role, like 'class' or 'method'.

  • uri (str) –

    The item URI.

  • priority (int, default: 1 ) –

    The item priority. Only used internally by mkdocstrings and Sphinx.

  • dispname (str | None, default: None ) –

    The item display name.

Methods:

  • format_sphinx –

    Format this item as a Sphinx inventory line.

  • parse_sphinx –

    Parse a line from a Sphinx v2 inventory file and return an InventoryItem from it.

Source code in src/mkdocstrings/inventory.py 
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
def __init__(
    self,
    name: str,
    domain: str,
    role: str,
    uri: str,
    priority: int = 1,
    dispname: str | None = None,
):
    """Initialize the object.

    Arguments:
        name: The item name.
        domain: The item domain, like 'python' or 'crystal'.
        role: The item role, like 'class' or 'method'.
        uri: The item URI.
        priority: The item priority. Only used internally by mkdocstrings and Sphinx.
        dispname: The item display name.
    """
    self.name: str = name
    self.domain: str = domain
    self.role: str = role
    self.uri: str = uri
    self.priority: int = priority
    self.dispname: str = dispname or name

format_sphinx ¤

format_sphinx() -> str

Format this item as a Sphinx inventory line.

Returns:

  • str –

    A line formatted for an objects.inv file.

Source code in src/mkdocstrings/inventory.py 
43
44
45
46
47
48
49
50
51
52
53
54
55
def format_sphinx(self) -> str:
    """Format this item as a Sphinx inventory line.

    Returns:
        A line formatted for an `objects.inv` file.
    """
    dispname = self.dispname
    if dispname == self.name:
        dispname = "-"
    uri = self.uri
    if uri.endswith(self.name):
        uri = uri[: -len(self.name)] + "$"
    return f"{self.name} {self.domain}:{self.role} {self.priority} {uri} {dispname}"

parse_sphinx classmethod ¤

parse_sphinx(line: str) -> InventoryItem

Parse a line from a Sphinx v2 inventory file and return an InventoryItem from it.

Source code in src/mkdocstrings/inventory.py 
59
60
61
62
63
64
65
66
67
68
69
70
@classmethod
def parse_sphinx(cls, line: str) -> InventoryItem:
    """Parse a line from a Sphinx v2 inventory file and return an `InventoryItem` from it."""
    match = cls.sphinx_item_regex.search(line)
    if not match:
        raise ValueError(line)
    name, domain, role, priority, uri, dispname = match.groups()
    if uri.endswith("$"):
        uri = uri[:-1] + name
    if dispname == "-":
        dispname = name
    return cls(name, domain, role, uri, int(priority), dispname)