fcode
/
delarte
3
2
Fork 1
Code Issues 1 Pull Requests 1 Projects 1 Releases Activity

CLI argument/options and default behaviours #1

New Issue
Closed
opened 2022-12-07 00:57:18 +00:00 by remace07 · 14 comments
remace07 commented 2022-12-07 00:57:18 +00:00
Collaborator
Copy Link

en: the project seems to work on my machine with the example given in README.md, but optionnal and/or needed arguments are not listed anywhere. maybe a documentation on usage would help if the script is getting more complex.

this may look like a simple man page:

help: 

./delarte.py <link> <?subtitles>

link: URL to the video page on Arte's website
subtitles: code for subtitles to download with the video

+ short description on what the script does

a suggestion would be to put this information in README.md, by adding a prototype Part in "Chauffe Marcel".

fr: le projet semble fonctionner normalement sur ma machine avec l'exemple donné dans le README.md, mais la liste des arguments qu'on peut et/ou doit entrer n'est accessible nulle part. peut-être qu'un mode d'emploi serait utile si le script était amené à devenir plus complexe.

ça pourrait ressembler à une simple page de man:

aide: 

./delarte.py <link> <?subtitles>

link: URL vers la page de la vidéo sur le site d'Arte
subtitles: code des sous-titres à télécharger

+ description courte de ce que le script fait selon les arguments fournis

une idée simple, serait de mettre cette information dans le fichier README.md, en séparant la partie installation du projet "Chauffe Marcel", d'une nouvelle partie "prototype"

*en:* the project seems to work on my machine with the example given in README.md, but optionnal and/or needed arguments are not listed anywhere. maybe a documentation on usage would help if the script is getting more complex. this may look like a simple man page: ``` help: ./delarte.py <link> <?subtitles> link: URL to the video page on Arte's website subtitles: code for subtitles to download with the video + short description on what the script does ``` a suggestion would be to put this information in README.md, by adding a prototype Part in "Chauffe Marcel". ----- *fr:* le projet semble fonctionner normalement sur ma machine avec l'exemple donné dans le README.md, mais la liste des arguments qu'on peut et/ou doit entrer n'est accessible nulle part. peut-être qu'un mode d'emploi serait utile si le script était amené à devenir plus complexe. ça pourrait ressembler à une simple page de man: ``` aide: ./delarte.py <link> <?subtitles> link: URL vers la page de la vidéo sur le site d'Arte subtitles: code des sous-titres à télécharger + description courte de ce que le script fait selon les arguments fournis ``` une idée simple, serait de mettre cette information dans le fichier README.md, en séparant la partie installation du projet "Chauffe Marcel", d'une nouvelle partie "prototype"
remace07 started working 2022-12-07 01:07:18 +00:00
remace07 canceled time tracking 2022-12-07 01:07:24 +00:00
freezed commented 2022-12-08 16:36:30 +00:00
Owner
Copy Link

Merci pour la proposition 👏
L'idée est d'ajouter la gestion des arguments avec argparse pour ne pas avoir à mettre à jour le README.md à chaque fois.

Merci pour la proposition 👏 L'idée est d'ajouter la gestion des arguments avec [`argparse`](https://docs.python.org/3/library/argparse.html) pour ne pas avoir à mettre à jour le [`README.md`](https://git.afpy.org/fcode/delarte/src/branch/stable/README.md) à chaque fois.
freezed added a new dependency 2022-12-08 16:37:50 +00:00
#2 Choix du répertoire de téléchargement temporaire
freezed changed title from [suggestion] missing documentation to Gérer les paramètres du script avec Argparse 2022-12-08 16:40:20 +00:00
freezed added the
enhancement
 label 2022-12-08 16:41:38 +00:00
freezed added this to the devel project 2022-12-08 16:44:42 +00:00
Barbagus commented 2022-12-10 08:19:21 +00:00
Collaborator
Copy Link

This has been addressed without argparse for now. Calling the script without argument (or calling it with either -h or --help will show a usage message.

This has been addressed without argparse for now. Calling the script without argument (or calling it with either `-h` or `--help` will show a usage message.
👍 1
freezed commented 2022-12-10 12:04:14 +00:00
Owner
Copy Link

Please mention the last branch, merge request or commit with the implementation related to this isse and close this issue if necessary

A good practice is to mention this issue in the commit message to ease following-up

Please mention the last branch, merge request or commit with the implementation related to this isse and close this issue if necessary A good practice is to mention this issue in the commit message to ease following-up
Barbagus commented 2022-12-10 12:56:34 +00:00
Collaborator
Copy Link

Commit: 9593619c68

"A good practice is to mention this issue in the commit message to ease following-up" => wilco.

Commit: 9593619c68 "A good practice is to mention this issue in the commit message to ease following-up" => wilco.
freezed commented 2022-12-11 21:56:11 +00:00
Owner
Copy Link

Hi @remace07 , it looks good for me too, see at line 48

If we are missing something, feel free to re-open this issue or open a new one related with this one.

Hi @remace07 , it looks good for me too, see [at line 48](https://git.afpy.org/fcode/delarte/src/commit/9593619c68f31956eb9c8ea573fb53df9290fb16/README.md?display=source#L48) If we are missing something, feel free to re-open this issue or open a new one related with this one.
Barbagus reopened this issue 2022-12-13 16:29:46 +00:00
Barbagus changed title from Gérer les paramètres du script avec Argparse to CLI argument/options 2022-12-13 16:30:08 +00:00
Barbagus commented 2022-12-13 16:33:41 +00:00
Collaborator
Copy Link

I reopen this because it is likely that a non-trivial cli args/opts management will become necessary regarding #11, #8 and #12.

I reopen this because it is likely that a non-trivial cli args/opts management will become necessary regarding #11, #8 and #12.
Barbagus changed title from CLI argument/options to CLI argument/options and default behaviours 2022-12-13 16:38:47 +00:00
Barbagus commented 2022-12-16 06:56:38 +00:00
Collaborator
Copy Link

Taking the conversation from #17 over here as it is more a talk about user interface and functionalities than one about implementation.

To sum up, @remace07 proposes this interface:

delarte [options] <program_url>

Options
-------
  -h, --help
    Display this message.

  -l, --languages <version>
    Select <version> as a combination of audio/subtitles.
    
  -r --resolution <resolution>
    Select <resolution> as the video quality.

Where I suggest:

delarte [options] <program_url> [<version> [<resolution>]]

Options
-------
  -h, --help
    Display this message.

So it is kind of a named parameters vs. positional parameters situation.

I pointed out that there is no use case for providing only program_url and resolution (the only scenario enabled by using flags tha would not be possible in my suggestion).

Taking the conversation from #17 over here as it is more a talk about user interface and functionalities than one about implementation. To sum up, @remace07 proposes this interface: ``` delarte [options] <program_url> Options ------- -h, --help Display this message. -l, --languages <version> Select <version> as a combination of audio/subtitles. -r --resolution <resolution> Select <resolution> as the video quality. ``` Where I suggest: ``` delarte [options] <program_url> [<version> [<resolution>]] Options ------- -h, --help Display this message. ``` So it is kind of a _named parameters_ vs. _positional parameters_ situation. I pointed out that there is no use case for providing only `program_url` and `resolution` (the only scenario enabled by using flags tha would not be possible in my suggestion).
Barbagus commented 2022-12-16 07:14:38 +00:00
Collaborator
Copy Link

My response to #17

a user that provides a link, and a resolution but no language code would be badly interpreted by argparse: positionnal arguments HAVE TO be given in the very order of the prototype, because argparse creates a Namespace object, which is a key:value structure.

Understood however

  1. I think implementation should be dictated by functionality not the other way around.
  2. Both version and resolution could be validated by the argparse using simple regexps so it could be able to detect error and fail early. Although this would be a waste of time anyway as the validation can only really come after we downloaded the programs info (api) then the version's available resolutions.

All we need are nice error messages like "720p" is not a valid version identifier, available values are: ...

I think it is more "userproof" with flags [...] whether you want to guide the users but annoy them more, or guide less but annoy them less.

I am not sure I understand what you mean by "userproof", but I guess if the users do not know/remember the usage prototype they will hit -h anyway and will be provided with information, whether if it is to remember that the version comes before the resolution or to remember that -l is the flag for the version.

In other words, one can say "but positionnal arguments HAVE TO be given in the very order of the prototype" as much as one can say "but named arguments HAVE TO be given with the correct flag in front of them". The only way to know in both cases is to hit -h and read.

My response to #17 > a user that provides a link, and a resolution but no language code would be badly interpreted by argparse: positionnal arguments HAVE TO be given in the very order of the prototype, because argparse creates a Namespace object, which is a key:value structure. Understood however 1. I think implementation should be dictated by functionality not the other way around. 2. Both `version` and `resolution` could be validated by the `argparse` using simple regexps so it could be able to detect error and fail early. Although this would be a waste of time anyway as the validation can only really come after we downloaded the programs info (`api`) then the version's available resolutions. All we need are nice error messages like `"720p" is not a valid version identifier, available values are: ...` > I think it is more "userproof" with flags [...] whether you want to guide the users but annoy them more, or guide less but annoy them less. I am not sure I understand what you mean by "userproof", but I guess if the users do not know/remember the usage prototype they will hit `-h` anyway and will be provided with information, whether if it is to remember that the `version` comes before the `resolution` or to remember that `-l` is the flag for the `version`. In other words, one can say "but positionnal arguments HAVE TO be given in the very order of the prototype" as much as one can say "but named arguments HAVE TO be given with the correct flag in front of them". The only way to know in both cases is to hit `-h` and read.
Barbagus commented 2022-12-16 07:20:11 +00:00
Collaborator
Copy Link

I am not saying that flags must only be used for special cases (help message, version number, ...) or to overwrite default values or behaviours (human redable vs machine parsebale outputs, verbosity, logging...) but I am almost saying it =) For anything more complicated, groups (like with the git command) is probably more appropriate.

We have 3 usecases so far:

  1. I have a URL I want to know what versions are available.
  2. I have a URL and a version I want to know what resolution are available.
  3. I have a URL a version and a resolution I want to download that.

Unless we can already think of probable other scenarios to come, I don't see how flags helps us more.

I am not saying that flags must only be used for _special cases_ (help message, version number, ...) or to overwrite _default values or behaviours_ (human redable vs machine parsebale outputs, verbosity, logging...) but I am almost saying it =) For anything more complicated, _groups_ (like with the git command) is probably more appropriate. We have 3 usecases so far: 1. I have a URL I want to know what versions are available. 2. I have a URL and a version I want to know what resolution are available. 3. I have a URL a version and a resolution I want to download that. Unless we can already think of probable other scenarios to come, I don't see how flags helps us more.
remace07 commented 2022-12-16 10:17:30 +00:00
Author
Collaborator
Copy Link
I think implementation should be dictated by functionality not the other way around.

True

I am not sure I understand what you mean by "userproof", but I guess if the users do not know/remember the usage prototype [...]

that's what I meant.

  1. it is easier to remember what to enter (in the very order) when you also have flags
  2. flags make arguments not order-dependant

though, the workflow you imagine (first get available versions, then get available renditions, then download the asked combo) makes the argument come in the very order.

so I think You're right, flags don't help a lot, for instance. it's just that I misunderstood something from documentation.

``` I think implementation should be dictated by functionality not the other way around. ``` True ``` I am not sure I understand what you mean by "userproof", but I guess if the users do not know/remember the usage prototype [...] ``` that's what I meant. 1. it is easier to remember what to enter (in the very order) when you also have flags 2. flags make arguments not order-dependant though, the workflow you imagine (first get available versions, then get available renditions, then download the asked combo) makes the argument come in the very order. so I think You're right, flags don't help a lot, for instance. it's just that I misunderstood something from documentation.
Barbagus commented 2022-12-20 08:53:53 +00:00
Collaborator
Copy Link

Thanks @remace07 for the initial push with about this issue !

I suggest we keep this issue open to discusse future options/default values strategy.

Thanks @remace07 for the initial push with about this issue ! I suggest we keep this issue open to discusse future options/default values strategy.
Barbagus commented 2022-12-20 09:30:50 +00:00
Collaborator
Copy Link

Ok, implementation remark:

Does anyone have experience with docopt ?

It works in reverse from most arument parser:

  • argparse build parser programatically and is able to generate some usage string from it.
  • docopt does the oposite, you give it a usage string and it generates a parser for you.

It would be an added dependency, but I find it very elegant (functionality dictates implementation and not the opposite), actually I ❤️ the idea :)

If someone wants to experiement...

PS: the project seems not in developement for a long while, but if it does the job...

Ok, implementation remark: Does anyone have experience with [docopt](http://docopt.org/) ? It works _in reverse_ from most arument parser: - `argparse` build parser programatically and is able to generate some _usage string_ from it. - `docopt` does the oposite, you give it a _usage string_ and it generates a parser for you. It would be an added dependency, but I find it very elegant (functionality dictates implementation and not the opposite), actually I ❤️ the idea :) If someone wants to experiement... PS: the project seems not in developement for a long while, but if it does the job...
Barbagus commented 2022-12-20 13:40:23 +00:00
Collaborator
Copy Link

Okay, the orignal project (docopt) has been dormant but there was a community fork made few years ago: docopt-ng

Okay, the orignal project (docopt) has been dormant but there was a community fork made few years ago: [docopt-ng](https://pypi.org/project/docopt-ng/)
Barbagus commented 2023-01-11 17:17:57 +00:00
Collaborator
Copy Link

These options have been added to address output file naming (#8)

--name-use-id          use the program ID
--name-use-slug        use the URL slug
--name-sep=<sep>       field separator [default:  - ]
--name-seq-pfx=<pfx>   sequence counter prefix [default:  - ]
--name-seq-no-pad      disable sequence zero-padding
--name-add-resolution  add resolution tag

They all start with --name- so they can be easily gathered and passed to the naming routine.

These options have been added to address output file naming (#8) ``` --name-use-id use the program ID --name-use-slug use the URL slug --name-sep=<sep> field separator [default: - ] --name-seq-pfx=<pfx> sequence counter prefix [default: - ] --name-seq-no-pad disable sequence zero-padding --name-add-resolution add resolution tag ``` They all start with `--name-` so they can be easily gathered and passed to the naming routine.
Sign in to join this conversation.
No Branch/Tag Specified
Branches Tags
stable
model
devel
draft
Labels
Clear labels   
bug

Something is not working

  
duplicate

This issue or pull request already exists

  
enhancement

New feature

  
help wanted

Need some help

  
invalid

Something is wrong

  
question

More information is needed

  
wontfix

This won't be fixed

No Label
bug
duplicate
enhancement
help wanted
invalid
question
wontfix
Milestone
Clear milestone
No items
No Milestone
Projects
Clear projects
No project
devel
Assignees
Clear assignees
No Assignees
3 Participants
Notifications
Due Date
The due date is invalid or out of range. Please use the format 'yyyy-mm-dd'.

No due date set.

Blocks
#2 Choix du répertoire de téléchargement temporaire
fcode/delarte
Reference: fcode/delarte#1
No description provided.
Delete Branch "%!s(<nil>)"

Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?