No information on console-scripts `type` option

[yeoffrey]

Issue Kind

Improving documentation

Existing Link

https://python-poetry.org/docs/pyproject/#scripts

Description

✅ Happy to add this myself in a PR

There is no mention of the type option, or any options at all when defining scripts in the pyproject.toml file. I've been trying to migrate over to Poetry and needed to replace my console-scripts in my setup.cfg file. I couldn't find any information on how to do this with Poetry from the documentation.

I found the answer in this thread here, where @evilhamsterman correctly points out that this is missing and should be present in the docs. I wish this was just in the main area, can I please make a PR and add an explanation there?

[dimbleby]

you do not need permission to make a pull request - but you should first check for duplicates...

[yeoffrey]

you do not need permission to make a pull request - but you should first check for duplicates...

I did search for duplicates for this and could not find one which covers the entire section of the documentation.

[evilhamsterman]

Before there's a PR there needs to be more information about the option from someone who does know the code. Which is why I asked the question in the first place and asked for someone who does know to provide the answer. I never got a good answer to my question just a link to an 8 year old website that doesn't have any obvious association to the option in question.

In fact it looks like the documentation is even worse than before because the type option isn't even in an example anymore.

The questions I see are

1. Is it even actually an option? As mentioned there is absolutely no documentation about it, even less than before. Before there was at least an example but that example has since been deleted
2. What are the valid options for type?
   • If type="console" is the same as the console_scripts in the packaging spec, we can assume the analogous option for gui_scripts is it just type="gui", but is that true?
   • What about the deprecated script option, is that supported at all?

[dimbleby]

there is a schema and really not very much code to read over in poetry-core. If this is still of interest to you, you can soon make yourself the expert.

proposed pull request risks duplicating or at least overlapping #9572, so be aware of that.

as an issue this is duplicate of both the discussion that it references and #9510: please close it out.

[evilhamsterman]

@dimbleby do you know the answer to these questions?

Apparently the fact that the tools.poetry.scripts option is poorly documented has come up a few times and every time your response has been less than helpful. Once just a link to a really outdated site without any information on the available options in Poetry and potentially some Python packaging options that are invalid in Poetry. Then this time you just a link to a search for some code and the instructions that essentially boil down to "figure it out yourself and fix it for me". It's like if someone went to a car dealership with a question about what a button does in their car and their response was "There's a Napa down the street, go get some tools figure it out and let me know".

If someone is asking questions that means they, for some reason, are unable to find out themselves. Maybe they don't have the skills, maybe they just don't have the time, or maybe something else. The point is they're asking for help and your response shouldn't be just "you go figure it out." If you don't know the answer then you should find someone who does. This is obviously a miss in the docs. I didn't follow up last year because your I didn't have the time to dig into the code to figure out what the different options are and what they do.

It's "really not very much code" is not true. If it's not very much code why couldn't you have taken care of it? Your search links to many different files which you'd have to figure out what's relevant. Then find the section of the file which processes the options, then to figure out what the results of those processes do you have to figure out what is calling that method, then figure out what it is doing with the result of the options, which leads to calling out to something else...... That's why I reached out to someone who is a maintainer because I didn't have time to figure it out and thought maybe someone who was more familiar would recognize the miss and be able to create the documentation quicker and more efficiently than I could. Maybe one of the people who committed some of the code in question perhaps.

Now some others apparently do have the time to try and help figure it out and fix the issue, but it also looks like they don't fully grasp all the available options, because the other PR is trying to document the type="file" option but omits the type="console" option that I was asking about before. So we've gone from one option being mentioned in and example, that got deleted and now we have a different option being documented without any information about the other.

[dimbleby]

I am not your car dealership. It is the nature of open source that change happens when a motivated person shows up and makes it happen.

So far as this question goes, I am not that person.

If you also aren't willing or able to get this done - that's fine, but please don't try to make it my fault.

[yeoffrey]

there is a schema and really not very much code to read over in poetry-core. If this is still of interest to you, you can soon make yourself the expert.

proposed pull request risks duplicating or at least overlapping #9572, so be aware of that.

as an issue this is duplicate of both the discussion that it references and #9510: please close it out.

I don't believe that this is a duplicate. This refers to a different option entirely.

I'm fine to read this code and write the docs. Will do that sometime this week.