Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

AssertionError: OSError: If there is an error while writing to the file. Help would be appreciated #689

Closed
MartinRJDagleish opened this issue May 10, 2024 · 1 comment
Closed

AssertionError: OSError: If there is an error while writing to the file. Help would be appreciated #689

MartinRJDagleish opened this issue May 10, 2024 · 1 comment
Labels
bug

Comments

@MartinRJDagleish
Copy link

Problem Description

AssertionError:     OSError: If there is an error while writing to the file.

Is raised, when I run pdoc with the following flags

pdoc --math -d numpy -t ./docs/template -o ./docs/html smPyFLIM
Full stacktrace 
Traceback (most recent call last):
  File "/run/media/mrjd/DATA/University/Master_LMU/Praktika/PC-F-Praktikum/smPyFLIM/.venv/bin/pdoc", line 8, in <module>
    sys.exit(cli())
             ^^^^^
  File "/run/media/mrjd/DATA/University/Master_LMU/Praktika/PC-F-Praktikum/smPyFLIM/.venv/lib/python3.11/site-packages/pdoc/__main__.py", line 199, in cli
    pdoc.pdoc(
  File "/run/media/mrjd/DATA/University/Master_LMU/Praktika/PC-F-Praktikum/smPyFLIM/.venv/lib/python3.11/site-packages/pdoc/__init__.py", line 513, in pdoc
    out = render.html_module(module, all_modules)
          ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/usr/lib/python3.11/contextlib.py", line 81, in inner
    return func(*args, **kwds)
           ^^^^^^^^^^^^^^^^^^^
  File "/run/media/mrjd/DATA/University/Master_LMU/Praktika/PC-F-Praktikum/smPyFLIM/.venv/lib/python3.11/site-packages/pdoc/render.py", line 106, in html_module
    return env.get_template("module.html.jinja2").render(
           ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/run/media/mrjd/DATA/University/Master_LMU/Praktika/PC-F-Praktikum/smPyFLIM/.venv/lib/python3.11/site-packages/jinja2/environment.py", line 1304, in render
    self.environment.handle_exception()
  File "/run/media/mrjd/DATA/University/Master_LMU/Praktika/PC-F-Praktikum/smPyFLIM/.venv/lib/python3.11/site-packages/jinja2/environment.py", line 939, in handle_exception
    raise rewrite_traceback_stack(source=source)
  File "/run/media/mrjd/DATA/University/Master_LMU/Praktika/PC-F-Praktikum/smPyFLIM/.venv/lib/python3.11/site-packages/pdoc/templates/default/module.html.jinja2", line 311, in top-level template code
    {%- if loop.nextitem -%}
^^^^^^^^^^^^^^^^^
  File "/run/media/mrjd/DATA/University/Master_LMU/Praktika/PC-F-Praktikum/smPyFLIM/.venv/lib/python3.11/site-packages/pdoc/templates/default/frame.html.jinja2", line 36, in top-level template code
    {% block body %}
    ^^^^^^^^^^^^^^^^^
  File "/run/media/mrjd/DATA/University/Master_LMU/Praktika/PC-F-Praktikum/smPyFLIM/.venv/lib/python3.11/site-packages/pdoc/templates/default/frame.html.jinja2", line 42, in block 'body'
    {% block content %}{% endblock %}
^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/run/media/mrjd/DATA/University/Master_LMU/Praktika/PC-F-Praktikum/smPyFLIM/.venv/lib/python3.11/site-packages/pdoc/templates/default/module.html.jinja2", line 101, in block 'content'
    {% block module_contents %}
^^^^^^^^^^^^^^^^^^^^^
  File "/run/media/mrjd/DATA/University/Master_LMU/Praktika/PC-F-Praktikum/smPyFLIM/.venv/lib/python3.11/site-packages/pdoc/templates/default/module.html.jinja2", line 108, in block 'module_contents'
    {{ member(m) }}

  File "/run/media/mrjd/DATA/University/Master_LMU/Praktika/PC-F-Praktikum/smPyFLIM/.venv/lib/python3.11/site-packages/jinja2/runtime.py", line 782, in _invoke
    rv = self._func(*arguments)
         ^^^^^^^^^^^^^^^^^^^^^^
  File "/run/media/mrjd/DATA/University/Master_LMU/Praktika/PC-F-Praktikum/smPyFLIM/.venv/lib/python3.11/site-packages/pdoc/templates/default/module.html.jinja2", line 208, in template
    {{ docstring(doc) }}
^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/run/media/mrjd/DATA/University/Master_LMU/Praktika/PC-F-Praktikum/smPyFLIM/.venv/lib/python3.11/site-packages/jinja2/runtime.py", line 782, in _invoke
    rv = self._func(*arguments)
         ^^^^^^^^^^^^^^^^^^^^^^
  File "/run/media/mrjd/DATA/University/Master_LMU/Praktika/PC-F-Praktikum/smPyFLIM/.venv/lib/python3.11/site-packages/pdoc/templates/default/module.html.jinja2", line 212, in template
    <div class="docstring">{{ var.docstring | replace("@public", "") | to_markdown | to_html | linkify(namespace=var.qualname) }}</div>
^^^^^^^^^^^^^^^^^^^^^
  File "/run/media/mrjd/DATA/University/Master_LMU/Praktika/PC-F-Praktikum/smPyFLIM/.venv/lib/python3.11/site-packages/pdoc/render_helpers.py", line 192, in to_markdown_with_context
    return to_markdown(docstring, module, docformat)
           ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/run/media/mrjd/DATA/University/Master_LMU/Praktika/PC-F-Praktikum/smPyFLIM/.venv/lib/python3.11/site-packages/pdoc/render_helpers.py", line 197, in to_markdown
    return docstrings.convert(docstring, docformat, module.source_file)
           ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/run/media/mrjd/DATA/University/Master_LMU/Praktika/PC-F-Praktikum/smPyFLIM/.venv/lib/python3.11/site-packages/pdoc/docstrings.py", line 42, in convert
    docstring = numpy(docstring)
                ^^^^^^^^^^^^^^^^
  File "/run/media/mrjd/DATA/University/Master_LMU/Praktika/PC-F-Praktikum/smPyFLIM/.venv/lib/python3.11/site-packages/pdoc/docstrings.py", line 198, in numpy
    contents += f"###### {heading}\n{_numpy_parameters(content)}"
                                     ^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/run/media/mrjd/DATA/University/Master_LMU/Praktika/PC-F-Praktikum/smPyFLIM/.venv/lib/python3.11/site-packages/pdoc/docstrings.py", line 226, in _numpy_parameters
    for item in _indented_list(content):
                ^^^^^^^^^^^^^^^^^^^^^^^
  File "/run/media/mrjd/DATA/University/Master_LMU/Praktika/PC-F-Praktikum/smPyFLIM/.venv/lib/python3.11/site-packages/pdoc/docstrings.py", line 149, in _indented_list
    assert not contents.startswith(" "), contents
AssertionError:     OSError: If there is an error while writing to the file.

I am not quite sure, what causes this issues and I am not quite sure, what the stacktrace should tell me.
Why would there be a problem, while writing to the file?

If the template file, helps that I use, here it is:

Template File for math with `KaTeX` 
{# This template is included in math mode and loads MathJax for formula rendering. #}
{#<script type="text/x-mathjax-config">
  MathJax.Hub.Config({tex2jax: {inlineMath: [['$','$'], ['\\(','\\)']]}});
</script>
<script id="MathJax-script" async src="http://cdn.mathjax.org/mathjax/latest/MathJax.js?config=TeX-AMS-MML_HTMLorMML"></script>
<script>
    /* Re-invoke MathJax when DOM content changes, for example during search. */
    document.addEventListener("DOMContentLoaded", () => {
        new MutationObserver(() => MathJax.typeset()).observe(
            document.querySelector("main.pdoc").parentNode,
            {childList: true}
        );
    })
</script>
<style>
    mjx-container {
        overflow-x: auto;
        overflow-y: hidden;
    }
</style>
#}

<script src="https://polyfill.io/v3/polyfill.min.js?features=es6"></script>
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/[email protected]/dist/katex.min.css" integrity="sha384-wcIxkf4k558AjM3Yz3BBFQUbk/zgIYC2R0QpeeYb+TwlBVMrlgLqwRjRtGZiK7ww" crossorigin="anonymous">
<script defer src="https://cdn.jsdelivr.net/npm/[email protected]/dist/katex.min.js" integrity="sha384-hIoBPJpTUs74ddyc4bFZSM1TVlQDA60VBbJS0oA934VSz82sBx1X7kSx2ATBDIyd" crossorigin="anonymous"></script>
<script defer src="https://cdn.jsdelivr.net/npm/[email protected]/dist/contrib/auto-render.min.js" integrity="sha384-43gviWU0YVjaDtb/GhzOouOXtZMP/7XUzwPTstBeZFe/+rCMvRwr4yROQP43s0Xk" crossorigin="anonymous"></script>
<script>
    document.addEventListener("DOMContentLoaded", function() {
        renderMathInElement(document.body, {
          // customised options
          // • auto-render specific keys, e.g.:
          delimiters: [
              {left: '$$', right: '$$', display: true},
              {left: '$', right: '$', display: false},
              {left: '\\(', right: '\\)', display: false},
              {left: '\\[', right: '\\]', display: true}
          ],
          // • rendering keys, e.g.:
          throwOnError : false
        });
    });
</script>
<style>
    mjx-container {
        overflow-x: auto;
        overflow-y: hidden;
    }
</style>

I am not a web dev, so please excuse my bad template code. I just briefly put this togehter to have KaTeX support instead of MathJax (I wanted the lightweight and fast rendering).

Steps to reproduce the behavior

  • Use pdoc with commands as specified as above

System Information

Paste the output of "pdoc --version" here.

> pdoc --version 
pdoc: 14.4.0
Python: 3.11.8
Platform: Linux-6.6.26-1-MANJARO-x86_64-with-glibc2.39
@MartinRJDagleish
Copy link
Author

MartinRJDagleish commented May 13, 2024 •
edited

Solution

I debugged the pdoc code base with the flags from above and then stepped throug the doc generation.
There I noticed, that the crash was always happening in a certain module.

I investigated my code further and after some examination, I found that my docstring was wrongly formatted (not according to numpydoc format).

Error inducing code snippet (shortened):

class Foo:
    @classmethod
    def ser_and_write_to_file(cls, fit_sett: FitSett, fpath: Path | str) -> None:
        """
        Write the serialized representation of the `fit_sett` object to a file specified by `fpath`.

        Parameters
        ----------
        fit_sett: FitSett
            The object to be serialized and written to the file.
        fpath: Path | str
            The path to the file where the serialized representation will be written.

        Raises
        ------
            OSError: If there is an error while writing to the file.

        Returns
        -------
        None
        """

instead of the correct:

class Foo:
    @classmethod
    def ser_and_write_to_file(cls, fit_sett: FitSett, fpath: Path | str) -> None:
        """
        Write the serialized representation of the `fit_sett` object to a file specified by `fpath`.

        Parameters
        ----------
        fit_sett: FitSett
            The object to be serialized and written to the file.
        fpath: Path | str
            The path to the file where the serialized representation will be written.

        Raises
        ------
        OSError
            If there is an error while writing to the file.

        Returns
        -------
        None
        """

I think I got some docstring style wrong or just did not notice. Anyways this fixes the issue now.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Assignees
No one assigned
Labels
bug
Projects
None yet
Milestone
No milestone
Development

No branches or pull requests
1 participant
@MartinRJDagleish