Skip to content

Commit 0723fc2

Browse files
pawamoypawamoy
committed
refactor: Finish exposing/hiding public/internal objects
1 parent 72e8bae commit 0723fc2

11 files changed

Lines changed: 144 additions & 120 deletions

File tree

‎src/mkdocstrings/__init__.py‎

Lines changed: 3 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -25,22 +25,18 @@
2525
)
2626
from mkdocstrings._internal.inventory import Inventory, InventoryItem
2727
from mkdocstrings._internal.loggers import (
28+
TEMPLATES_DIRS,
2829
LoggerAdapter,
2930
TemplateLogger,
3031
get_logger,
3132
get_template_logger,
3233
get_template_logger_function,
3334
get_template_path,
3435
)
35-
from mkdocstrings._internal.plugin import (
36-
InventoryImportType,
37-
InventoryLoaderType,
38-
MkdocstringsPlugin,
39-
PluginConfig,
40-
list_to_tuple,
41-
)
36+
from mkdocstrings._internal.plugin import MkdocstringsPlugin, PluginConfig
4237

4338
__all__: list[str] = [
39+
"TEMPLATES_DIRS",
4440
"AutoDocProcessor",
4541
"BaseHandler",
4642
"CollectionError",
@@ -52,9 +48,7 @@
5248
"Highlighter",
5349
"IdPrependingTreeprocessor",
5450
"Inventory",
55-
"InventoryImportType",
5651
"InventoryItem",
57-
"InventoryLoaderType",
5852
"LoggerAdapter",
5953
"MkdocstringsExtension",
6054
"MkdocstringsInnerExtension",
@@ -68,5 +62,4 @@
6862
"get_template_logger",
6963
"get_template_logger_function",
7064
"get_template_path",
71-
"list_to_tuple",
7265
]

‎src/mkdocstrings/_internal/download.py‎

Lines changed: 11 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -9,13 +9,13 @@
99

1010
from mkdocstrings._internal.loggers import get_logger
1111

12-
log = get_logger(__name__)
12+
_logger = get_logger(__name__)
1313

1414
# Regex pattern for an environment variable in the form ${ENV_VAR}.
15-
ENV_VAR_PATTERN = re.compile(r"\$\{([A-Za-z_][A-Za-z0-9_]*)\}")
15+
_ENV_VAR_PATTERN = re.compile(r"\$\{([A-Za-z_][A-Za-z0-9_]*)\}")
1616

1717

18-
def download_url_with_gz(url: str) -> bytes:
18+
def _download_url_with_gz(url: str) -> bytes:
1919
url, auth_header = _extract_auth_from_url(url)
2020

2121
req = urllib.request.Request( # noqa: S310
@@ -42,10 +42,14 @@ def replace_func(match: re.Match) -> str:
4242
try:
4343
return env[match.group(1)]
4444
except KeyError:
45-
log.warning("Environment variable '%s' is not set, but is used in inventory URL %s", match.group(1), url)
45+
_logger.warning(
46+
"Environment variable '%s' is not set, but is used in inventory URL %s",
47+
match.group(1),
48+
url,
49+
)
4650
return match.group(0)
4751

48-
return re.sub(ENV_VAR_PATTERN, replace_func, credential)
52+
return re.sub(_ENV_VAR_PATTERN, replace_func, credential)
4953

5054

5155
# Implementation adapted from PDM: https://github.com/pdm-project/pdm.
@@ -67,11 +71,11 @@ def _create_auth_header(credential: str, url: str) -> dict[str, str]:
6771
"""Create the Authorization header for basic or bearer authentication, depending on credential."""
6872
if ":" not in credential:
6973
# We assume that the user is using a token.
70-
log.debug("Using bearer token authentication for %s", url)
74+
_logger.debug("Using bearer token authentication for %s", url)
7175
return {"Authorization": f"Bearer {credential}"}
7276

7377
# Else, we assume that the user is using user:password.
7478
user, pwd = credential.split(":", 1)
75-
log.debug("Using basic authentication for %s", url)
79+
_logger.debug("Using basic authentication for %s", url)
7680
credentials = base64.encodebytes(f"{user}:{pwd}".encode()).decode().strip()
7781
return {"Authorization": f"Basic {credentials}"}

‎src/mkdocstrings/_internal/extension.py‎

Lines changed: 31 additions & 30 deletions
Original file line numberDiff line numberDiff line change
@@ -1,25 +1,24 @@
1-
"""This module holds the code of the Markdown extension responsible for matching "autodoc" instructions.
2-
3-
The extension is composed of a Markdown [block processor](https://python-markdown.github.io/extensions/api/#blockparser)
4-
that matches indented blocks starting with a line like `::: identifier`.
5-
6-
For each of these blocks, it uses a [handler][mkdocstrings.BaseHandler] to collect documentation about
7-
the given identifier and render it with Jinja templates.
8-
9-
Both the collection and rendering process can be configured by adding YAML configuration under the "autodoc"
10-
instruction:
11-
12-
```yaml
13-
::: some.identifier
14-
handler: python
15-
options:
16-
option1: value1
17-
option2:
18-
- value2a
19-
- value2b
20-
option_x: etc
21-
```
22-
"""
1+
# This module holds the code of the Markdown extension responsible for matching "autodoc" instructions.
2+
#
3+
# The extension is composed of a Markdown [block processor](https://python-markdown.github.io/extensions/api/#blockparser)
4+
# that matches indented blocks starting with a line like `::: identifier`.
5+
#
6+
# For each of these blocks, it uses a [handler][mkdocstrings.BaseHandler] to collect documentation about
7+
# the given identifier and render it with Jinja templates.
8+
#
9+
# Both the collection and rendering process can be configured by adding YAML configuration under the "autodoc"
10+
# instruction:
11+
#
12+
# ```yaml
13+
# ::: some.identifier
14+
# handler: python
15+
# options:
16+
# option1: value1
17+
# option2:
18+
# - value2a
19+
# - value2b
20+
# option_x: etc
21+
# ```
2322

2423
from __future__ import annotations
2524

@@ -45,7 +44,7 @@
4544
from mkdocs_autorefs import AutorefsPlugin
4645

4746

48-
log = get_logger(__name__)
47+
_logger = get_logger(__name__)
4948

5049

5150
class AutoDocProcessor(BlockProcessor):
@@ -59,6 +58,7 @@ class AutoDocProcessor(BlockProcessor):
5958
"""
6059

6160
regex = re.compile(r"^(?P<heading>#{1,6} *|)::: ?(?P<name>.+?) *$", flags=re.MULTILINE)
61+
"""The regular expression to match our autodoc instructions."""
6262

6363
def __init__(
6464
self,
@@ -76,6 +76,7 @@ def __init__(
7676
"""
7777
super().__init__(parser=md.parser)
7878
self.md = md
79+
"""The Markdown instance."""
7980
self._handlers = handlers
8081
self._autorefs = autorefs
8182
self._updated_envs: set = set()
@@ -120,7 +121,7 @@ def run(self, parent: Element, blocks: MutableSequence[str]) -> None:
120121
if match:
121122
identifier = match["name"]
122123
heading_level = match["heading"].count("#")
123-
log.debug("Matched '::: %s'", identifier)
124+
_logger.debug("Matched '::: %s'", identifier)
124125

125126
html, handler, data = self._process_block(identifier, block, heading_level)
126127
el = Element("div", {"class": "mkdocstrings"})
@@ -161,7 +162,7 @@ def _process_block(
161162
local_config = yaml.safe_load(yaml_block) or {}
162163
handler_name = self._handlers.get_handler_name(local_config)
163164

164-
log.debug("Using handler '%s'", handler_name)
165+
_logger.debug("Using handler '%s'", handler_name)
165166
handler = self._handlers.get_handler(handler_name)
166167

167168
local_options = local_config.get("options", {})
@@ -183,23 +184,23 @@ def _process_block(
183184
global_options = handler_config.get("options", {})
184185
options = {**global_options, **local_options}
185186

186-
log.debug("Collecting data")
187+
_logger.debug("Collecting data")
187188
try:
188189
data: CollectorItem = handler.collect(identifier, options)
189190
except CollectionError as exception:
190-
log.error("%s", exception) # noqa: TRY400
191+
_logger.error("%s", exception) # noqa: TRY400
191192
raise PluginError(f"Could not collect '{identifier}'") from exception
192193

193194
if handler_name not in self._updated_envs: # We haven't seen this handler before on this document.
194-
log.debug("Updating handler's rendering env")
195+
_logger.debug("Updating handler's rendering env")
195196
handler._update_env(self.md, config=self._handlers._tool_config)
196197
self._updated_envs.add(handler_name)
197198

198-
log.debug("Rendering templates")
199+
_logger.debug("Rendering templates")
199200
try:
200201
rendered = handler.render(data, options)
201202
except TemplateNotFound as exc:
202-
log.error( # noqa: TRY400
203+
_logger.error( # noqa: TRY400
203204
"Template '%s' not found for '%s' handler and theme '%s'.",
204205
exc.name,
205206
handler_name,

‎src/mkdocstrings/_internal/handlers/__init__.py‎

Lines changed: 0 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1 +0,0 @@
1-
"""Handlers module."""

‎src/mkdocstrings/_internal/handlers/base.py‎

Lines changed: 19 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,6 @@
1-
"""Base module for handlers.
2-
3-
This module contains the base classes for implementing handlers.
4-
"""
1+
# Base module for handlers.
2+
#
3+
# This module contains the base classes for implementing handlers.
54

65
from __future__ import annotations
76

@@ -25,7 +24,7 @@
2524
# TODO: Replace with `from mkdocs.utils.cache import download_and_cache_url` when we depend on mkdocs>=1.5.
2625
from mkdocs_get_deps.cache import download_and_cache_url
2726

28-
from mkdocstrings._internal.download import download_url_with_gz
27+
from mkdocstrings._internal.download import _download_url_with_gz
2928
from mkdocstrings._internal.handlers.rendering import (
3029
HeadingShiftingTreeprocessor,
3130
Highlighter,
@@ -48,11 +47,14 @@
4847
from markdown import Extension
4948
from mkdocs_autorefs import AutorefsHookInterface
5049

51-
log = get_logger(__name__)
50+
_logger = get_logger(__name__)
5251

5352
CollectorItem = Any
53+
"""The type of the item returned by the `collect` method of a handler."""
5454
HandlerConfig = Any
55+
"""The type of the configuration of a handler."""
5556
HandlerOptions = Any
57+
"""The type of the options passed to a handler."""
5658

5759

5860
# Autodoc instructions can appear in nested Markdown,
@@ -201,9 +203,13 @@ def __init__(
201203
)
202204

203205
self.theme = theme
206+
"""The selected theme."""
204207
self.custom_templates = custom_templates
208+
"""The path to custom templates."""
205209
self.mdx = mdx
210+
"""The Markdown extensions to use."""
206211
self.mdx_config = mdx_config
212+
"""The configuration for the Markdown extensions."""
207213
self._md: Markdown | None = None
208214
self._headings: list[Element] = []
209215

@@ -240,6 +246,8 @@ def __init__(
240246
loader=FileSystemLoader(paths),
241247
auto_reload=False, # Editing a template in the middle of a build is not useful.
242248
)
249+
"""The Jinja environment."""
250+
243251
self.env.filters["convert_markdown"] = self.do_convert_markdown
244252
self.env.filters["heading"] = self.do_heading
245253
self.env.filters["any"] = do_any
@@ -587,6 +595,7 @@ def __init__(
587595
self._tool_config = tool_config
588596

589597
self.inventory: Inventory = Inventory(project=inventory_project, version=inventory_version)
598+
"""The objects inventory."""
590599

591600
self._inv_futures: dict[futures.Future, tuple[BaseHandler, str, Any]] = {}
592601

@@ -722,26 +731,26 @@ def _download_inventories(self) -> None:
722731
if to_download:
723732
thread_pool = futures.ThreadPoolExecutor(4)
724733
for handler, url, conf in to_download:
725-
log.debug("Downloading inventory from %s", url)
734+
_logger.debug("Downloading inventory from %s", url)
726735
future = thread_pool.submit(
727736
download_and_cache_url,
728737
url,
729738
datetime.timedelta(days=1),
730-
download=download_url_with_gz,
739+
download=_download_url_with_gz,
731740
)
732741
self._inv_futures[future] = (handler, url, conf)
733742
thread_pool.shutdown(wait=False)
734743

735744
def _yield_inventory_items(self) -> Iterator[tuple[str, str]]:
736745
if self._inv_futures:
737-
log.debug("Waiting for %s inventory download(s)", len(self._inv_futures))
746+
_logger.debug("Waiting for %s inventory download(s)", len(self._inv_futures))
738747
futures.wait(self._inv_futures, timeout=30)
739748
# Reversed order so that pages from first futures take precedence:
740749
for fut, (handler, url, conf) in reversed(self._inv_futures.items()):
741750
try:
742751
yield from handler.load_inventory(BytesIO(fut.result()), url, **conf)
743752
except Exception as error: # noqa: BLE001
744-
log.error("Couldn't load inventory %s through handler '%s': %s", url, handler.name, error) # noqa: TRY400
753+
_logger.error("Couldn't load inventory %s through handler '%s': %s", url, handler.name, error) # noqa: TRY400
745754
self._inv_futures = {}
746755

747756
@property

0 commit comments

Comments
 (0)