missing description of public interface in documentation

[jimka2001]

I don't see from the documentation (https://pycodestyle.pycqa.org/en/latest/api.html) how to call pycodestyle programmatically. I'd like to call a function, pass the path of a python file, and get back a list/set/iterable/collection of PEP issues, either strings, or objects from which I can extract a string.

Is there such a function/method? Is it in the documentation, or is it missing?

The only way I can figure out how to do this is to use process.Popen(['pycodestyle', the_file_name]), or if on windows process.Popen(['python', '-m', 'pycodestyle', the_file_name]) because pip on windows does not seem to install pycodestyle in the executable path. (maybe I'm reaching the wrong conclusion with regard to windows, as I'm not a windows expert).

This seems to be a very strange public interface, so I suspect there is an easier way. It would be nice if the public interface to obtaining the PEP issues programmatically didn't have to include OS specific checks in user code.

[asottile]

third method on StyleGuide from your link?

[jimka2001]

This is a big step forward. But the 3rd method input_file does not return a list of PEP issues; rather it prints them to stdout. Looks like it return the count of how many issues were found.
Do I need to capture stdout by some sort of re-direction? Or is there a different method I should call?

[sigmavirus24]

You can provide your own report class to capture them. It needs only implement what is documented for BaseReport

[jimka2001]

Sorry, but I don't see any documented method in BaseReport which returns a list of issues, or generator or or or. I see methods which count the issues, and methods which report the issues by printing them. There are some comments about collecting issues, but the documentation does not indicate how to access the collected issues without printing them and parsing the output. Anyway, I'm not confident about parsing the output.
A line looks like this:

/Users/jnewton/Repos/courses/dir-algebra-1/bcs-algebra-1/algebra/tests/../algebra/choose.py:8:1: E303 too many blank lines (3)

But the file name or the trailing text might contain a : so I don't really know how to parse the text output.

If I am expected to create a subclass of BaseReport, then I think I'd need a call which will give me programmatic access the the issues generated. Right? Or am I failing to understand something fundamental?

[asottile]

a bit annoying to need to repeat what was said above: you need to write a subclass of Base report

[sigmavirus24]

@jimka2001 If you subclass BaseReport you can add whatever additional attributes you want to store the issues and methods you like to return them to you. We have an API that maybe isn't the best documented but it will allow you to do exactly what you want. If you don't want to put in that work, you can instead use flake8 and flake8-json to get more easily machine parsed output.

[jimka2001]

a bit annoying to need to repeat what was said above: you need to write a subclass of Base report

No need to be annoyed, just state plainly that what I'm trying to do is impossible with the currently documented interface.

If I understand your terse response, I'd have to implement a subclass at the application level, which cannot use the publicly documented interface but rather depends on internal implementation details which may change in future releases and render the application code incompatible.

[asottile]

it's literally not impossible. I've done it before but you haven't even showed your attempt so it's a bit frustrating to try and help you when you're in "give me the code" mode

[sigmavirus24]

@jimka2001 It seems like you're engaging in a bad faith discussion here. You want something similar, and when provided with an interface that has stayed stable for something like a decade, you're accusing us of providing you something we intend to break. What you're attempting to do is far from impossible. It's just not possible with a single function in the API. As a result, I'm locking this.