Re: [Docutils-develop] Recent commit activity

[Adam T. <aat...@ou...>]

Dear Günter,

Thank you for the note. I shall aim to add more rationale in commit messages in future.
Thank you also for the comments, which I've briefly addressed below.

The overall aim with the test changes is to be able to use the standard library's ``unittest`` runner, which will alleviate some of the points you raise.

> r9135
>   tex2unichar.py is a generated file, changes will be lost with an
>   update from the database.
       
>   (I updated the generating script and prepared a fixup patch.)

I saw the note that it is generated, but I could not find the generating script in the repository (even in ``sandbox/``) -- please may you let me know where it is?
    
> r9140, r9141: Import ``DocutilsTestSupport`` from ``test``
> 
>   This commit breaks the ability to run individual test scripts from
>   their respective directories. This is (was) an important help when
>   working on the test scripts.

The unittest runner resolves this, though we are not quite at that point.
We could add an option to ``alltests.py`` to run only tests in a specific directory?

> r9145
>   Since when is _format_str() unused?
>   Does this affect reporting of test failures?

r9143 removed the redefinitions of ``assertEqual``, ``assertNotEqual``, etc, which were the only uses of  _format_str()
This allows using ``TestCase``'s specialised equality methods by type.
Differences in strings with newlines (the reported purpose of _format_str()) are handled well by TestCase

> r9146
>  DocutilsTestSupport must be imported before docutils
>  so that imports from docutils use the test-dirs parent directory
>  (in case we want to test a not installed Docutils version)

If alltests.py is used to run tests, this is still the case.
We could add an import of DTS to those modules again, though my aim eventually is to remove DTS.
Is testing an uninstalled Docutils a usecase that is widely relied upon?

> r9163
>   What happend to sys.stdout.flush()  ?

``.flush()`` is still called before running tests, I didn't see a reason to call it before the environment information print-outs, though if it is needed we should add it back in.

> r9165
>   compare_output() no longer prints the corresponding input in case of
>   assertion errors which makes finding problems in parser test suites
>   harder.

My aim for parser test suites is to improve the test harnesses further, so this is not a permanent removal.

> r9167
>   IMV, an encoded string ("bytes" object) is no "binary" output.
>   
>   I need some more time to understand the changes here.
>   
>   A StringOutput.encode() method that *decodes* bytes data seems
>   odd:
>  
>   @@ -581,6 +600,11 @@ class StringOutput(Output):
>   
>   +    def encode(self, data):
>   +        if isinstance(data, bytes):
>   +            return data.decode(self.encoding, self.error_handler)
>   +        return str(data)
>   +

Python 3 bytes objects are sequences of 8-bit bytes, so I would say that it is binary output, but perhaps we could improve here.
I think the naming of ``.encode()`` is unfortunate in this context, but StringOutput should return strings (text content) and BytesOutput should return bytes (binary content).

> r9168 Use ``.rstrip()`` instead
> 
>   This fails with multi-lined output if line endings in output and extended
>   differ.

For tests, I believe we should ensure that we have as little 'magic' as possible -- what we say we expect should be bit-for-bit identical to what we generate. In this sense I fixed the newline errors to ensure correctness.

> r9178 
>   In case we don't want to ship "quicktest.py" with the Docutils
>   distribution, we can still keep it in the Docutils repo and simply change:
  
>   -can be found in the ``tools/`` directory of the Docutils distribution)
>   +can be found in the ``tools/`` directory of the Docutils repository)

I was actually going to suggest deleting "quicktest.py" entirely--finding the version can now be done with "docutils --version" and the last substantive change in functionality was 2006. "EasyDialogs" was removed in Python 2.7.

> r9179, r9180
>   there should be a way to avoid this code repetition

In general for tests I am more open to repetition as it is useful to be explicit about what is being tested, though I intend to refactor the functional tests, which hopefully will help achieve this goal.

Thanks,
Adam