pycommons.dev package

Developer tools.

Subpackages

Submodules

pycommons.dev.url_replacer module

Process a markdown file in order to make it useful for distribution.

In order to let sphinx properly load and insert the README.md file into the project’s documentation, we need to process this file from the GitHub style markdown to a variant suitable for the myst parser used in sphinx. While we are at it, we can also turn absolute URLs from the GitHub-README.md file that point to the documentation URL to relative URLs.

pycommons.dev.url_replacer.make_url_replacer(base_urls=None, full_urls=None, for_markdown=True)[source]

Create the url replacers that fix absolute to relative URLs.

Parameters:

  • base_urls (Optional[Mapping[str, str]], default: None) – a mapping of basic urls to shortcuts

  • full_urls (Optional[Mapping[str, str]], default: None) – a mapping of full urls to abbreviations

  • for_markdown (bool, default: True) – should the replace be for Markdown (True) or for HTML only (False)

Return type:

Callable[[str], str]

Returns:

a single callable that can process strings and fix the URLs therein

Raises:

  • TypeError – if any of the inputs is of the wrong type

  • ValueError – if any of the inputs is incorrect

>>> f = make_url_replacer(None, None)
>>> f("1")
'1'

>>> f = make_url_replacer({"https://example.com/1": "./a/",
...                          "https://example.com": "./"},
...                         {"https://example.com/1/1.txt": "y.txt",
...                          "https://example.com/x/1.txt": "z.txt"})
>>> f("<a href='http://example.com/1/2.txt' />")
'<a href="./a/2.txt" />'
>>> f("<a href='http://example.com/1' />")
'<a href="./a/" />'
>>> f("<a href='http://example.com' />")
'<a href="./" />'
>>> f("<a href='http://example.com/x.txt' />")
'<a href="./x.txt" />'
>>> f("<a href='http://example.com/1/1.txt' />")
'<a href="y.txt" />'
>>> f("<a href='http://example.com/x/1.txt' />")
'<a href="z.txt" />'

>>> try:
...     make_url_replacer(1, None)
... except TypeError as te:
...     print(te)
base_urls should be an instance of typing.Mapping but is int, namely 1.

>>> try:
...     make_url_replacer(None, 1)
... except TypeError as te:
...     print(te)
full_urls should be an instance of typing.Mapping but is int, namely 1.

>>> try:
...     make_url_replacer(None, None, None)
... except TypeError as te:
...     print(te)
for_markdown should be an instance of bool but is None.

>>> try:
...     make_url_replacer(None, None, 1)
... except TypeError as te:
...     print(te)
for_markdown should be an instance of bool but is int, namely 1.