<commit_before>#+TITLE: click

* Table of Contents :TOC_2_gh:
- [[#overview][Overview]]
- [[#reference][Reference]]
  - [[#echo-secho][echo, secho]]
  - [[#option][option]]
  - [[#param_decls][param_decls]]
  - [[#path][Path]]
  - [[#callback][callback]]
- [[#samples][Samples]]
  - [[#arguments][Arguments]]
- [[#how-to][How-to]]
  - [[#handle-exceptions][Handle exceptions]]

* Overview
#+BEGIN_SRC python
  @click.command()
  @click.option('--count', default=1, help='number of greetings')
  @click.argument('name')
  def hello(count, name):
      for x in range(count):
          click.echo('Hello %s!' % name)
#+END_SRC

#+BEGIN_SRC python
  @click.group()
  def cli():
      pass

  @cli.command()
  def initdb():
      click.echo('Initialized the database')

  @cli.command()
  def dropdb():
      click.echo('Dropped the database')
#+END_SRC

* Reference
** echo, secho
:REFERENCES:
- http://click.pocoo.org/5/utils/#printing-to-stdout
:END:

#+BEGIN_SRC python
  click.echo('Hello World!')
  click.echo(b'\xe2\x98\x83', nl=False)
  click.echo('Hello World!', err=True)

  click.secho('Hello World!', fg='green')
  click.secho('Some more text', bg='blue', fg='white')
  click.secho('ATTENTION', blink=True, bold=True)
#+END_SRC

** option
#+BEGIN_SRC python
  @click.option('--n', default=1)
  @click.option('--pos', nargs=2, type=float)
  @click.option('--item', type=(unicode, int))
  @click.option('--message', '-m', multiple=True)  #  -m foo -m bar
  @click.option('--shout/--no-shout', default=False)
  @click.option('--shout', is_flag=True)
  @click.option('--hash-type', type=click.Choice(['md5', 'sha1']))
  @click.option('--name', prompt='Your name please')
  @click.option('--username', envvar='USERNAME')
#+END_SRC

:REFERENCES:
- http://click.pocoo.org/5/options/
:END:

** param_decls
- ~Parameter~ is the base class of ~option~ and ~argument~.
- Positional arguments of ~option~ and ~argument~ become ~param_decl~
- If a string is added *without any dashes*, it becomes the parameter name.
- The parameter name is generated automatically by taking *the longest argument and converting all dashes to underscores.*

#+BEGIN_SRC python
  @click.option('-v', count=True)
  def foo(v):

  @click.option('-v', '--verbose', count=True)  # longest n
  def foo(verbose):

  @click.option('vvv', '-v', '--verbose', count=True)
  def foo(vvv):
#+END_SRC

:REFERENCES:
- http://click.pocoo.org/5/parameters/#parameter-names
- http://click.pocoo.org/5/api/#parameters
:END:

** Path
: class click.Path(exists=False, file_okay=True, dir_okay=True, writable=False, readable=True, resolve_path=False)

:REFERENCES:
- http://click.pocoo.org/5/api/#click.Path
:END:

** callback
#+BEGIN_SRC python
  import urllib

  def open_url(ctx, param, value):
      if value is not None:
          ctx.params['fp'] = urllib.urlopen(value)
          return value

  @click.command()
  @click.option('--url', callback=open_url)
  def cli(url, fp=None):
      if fp is not None:
          click.echo('%s: %s' % (url, fp.code))
#+END_SRC
- Can modify ~ctx.params~ to overwrite other parameters
- ~param~ is the ~Parameter~ object
- ~value~ is the actaul value

:REFERENCES:
- http://click.pocoo.org/5/advanced/#parameter-modifications
:END:

* Samples
** Arguments
#+BEGIN_SRC python
  @click.argument('src', nargs=-1)
  @click.argument('dst', nargs=1)
  @click.argument('input', type=click.File('rb'))
  @click.argument('output', type=click.File('wb'))
  @click.argument('f', type=click.Path(exists=True))
  @click.argument('src', envvar='SRC', type=click.File('r'))
  @click.argument('files', nargs=-1, type=click.Path())
#+END_SRC

:REFERENCES:
- http://click.pocoo.org/5/arguments/
:END:

* How-to
** Handle exceptions
:REFERENCES:
- http://click.pocoo.org/5/exceptions/
- https://github.com/pallets/click/issues/270
- http://click.pocoo.org/5/api/#click.ClickException
:END:

~click.Abort~ just exits with code 1, shows nothing but a message ~Aborted!~.

It seems okay to just use ~sys.exit()~, but there are some click exceptions available to handle it with default behaviors.

#+BEGIN_QUOTE
If an ~ClickException~ is raised, invoke the ~ClickException.show()~ method on it to display it and then exit the program with ~ClickException.exit_code~.
#+END_QUOTE

- ~UsageError~
- ~BadParameter~
- ~FileError~<commit_msg>Write about click auto complete<commit_after>#+TITLE: click

* Table of Contents :TOC_2_gh:
- [[#overview][Overview]]
- [[#reference][Reference]]
  - [[#echo-secho][echo, secho]]
  - [[#option][option]]
  - [[#param_decls][param_decls]]
  - [[#path][Path]]
  - [[#callback][callback]]
- [[#samples][Samples]]
  - [[#arguments][Arguments]]
- [[#how-to][How-to]]
  - [[#handle-exceptions][Handle exceptions]]
  - [[#support-auto-complete][Support auto complete]]

* Overview
#+BEGIN_SRC python
  @click.command()
  @click.option('--count', default=1, help='number of greetings')
  @click.argument('name')
  def hello(count, name):
      for x in range(count):
          click.echo('Hello %s!' % name)
#+END_SRC

#+BEGIN_SRC python
  @click.group()
  def cli():
      pass

  @cli.command()
  def initdb():
      click.echo('Initialized the database')

  @cli.command()
  def dropdb():
      click.echo('Dropped the database')
#+END_SRC

* Reference
** echo, secho
:REFERENCES:
- http://click.pocoo.org/5/utils/#printing-to-stdout
:END:

#+BEGIN_SRC python
  click.echo('Hello World!')
  click.echo(b'\xe2\x98\x83', nl=False)
  click.echo('Hello World!', err=True)

  click.secho('Hello World!', fg='green')
  click.secho('Some more text', bg='blue', fg='white')
  click.secho('ATTENTION', blink=True, bold=True)
#+END_SRC

** option
#+BEGIN_SRC python
  @click.option('--n', default=1)
  @click.option('--pos', nargs=2, type=float)
  @click.option('--item', type=(unicode, int))
  @click.option('--message', '-m', multiple=True)  #  -m foo -m bar
  @click.option('--shout/--no-shout', default=False)
  @click.option('--shout', is_flag=True)
  @click.option('--hash-type', type=click.Choice(['md5', 'sha1']))
  @click.option('--name', prompt='Your name please')
  @click.option('--username', envvar='USERNAME')
#+END_SRC

:REFERENCES:
- http://click.pocoo.org/5/options/
:END:

** param_decls
- ~Parameter~ is the base class of ~option~ and ~argument~.
- Positional arguments of ~option~ and ~argument~ become ~param_decl~
- If a string is added *without any dashes*, it becomes the parameter name.
- The parameter name is generated automatically by taking *the longest argument and converting all dashes to underscores.*

#+BEGIN_SRC python
  @click.option('-v', count=True)
  def foo(v):

  @click.option('-v', '--verbose', count=True)  # longest n
  def foo(verbose):

  @click.option('vvv', '-v', '--verbose', count=True)
  def foo(vvv):
#+END_SRC

:REFERENCES:
- http://click.pocoo.org/5/parameters/#parameter-names
- http://click.pocoo.org/5/api/#parameters
:END:

** Path
: class click.Path(exists=False, file_okay=True, dir_okay=True, writable=False, readable=True, resolve_path=False)

:REFERENCES:
- http://click.pocoo.org/5/api/#click.Path
:END:

** callback
#+BEGIN_SRC python
  import urllib

  def open_url(ctx, param, value):
      if value is not None:
          ctx.params['fp'] = urllib.urlopen(value)
          return value

  @click.command()
  @click.option('--url', callback=open_url)
  def cli(url, fp=None):
      if fp is not None:
          click.echo('%s: %s' % (url, fp.code))
#+END_SRC
- Can modify ~ctx.params~ to overwrite other parameters
- ~param~ is the ~Parameter~ object
- ~value~ is the actaul value

:REFERENCES:
- http://click.pocoo.org/5/advanced/#parameter-modifications
:END:

* Samples
** Arguments
#+BEGIN_SRC python
  @click.argument('src', nargs=-1)
  @click.argument('dst', nargs=1)
  @click.argument('input', type=click.File('rb'))
  @click.argument('output', type=click.File('wb'))
  @click.argument('f', type=click.Path(exists=True))
  @click.argument('src', envvar='SRC', type=click.File('r'))
  @click.argument('files', nargs=-1, type=click.Path())
#+END_SRC

:REFERENCES:
- http://click.pocoo.org/5/arguments/
:END:

* How-to
** Handle exceptions
:REFERENCES:
- http://click.pocoo.org/5/exceptions/
- https://github.com/pallets/click/issues/270
- http://click.pocoo.org/5/api/#click.ClickException
:END:

~click.Abort~ just exits with code 1, shows nothing but a message ~Aborted!~.

It seems okay to just use ~sys.exit()~, but there are some click exceptions available to handle it with default behaviors.

#+BEGIN_QUOTE
If an ~ClickException~ is raised, invoke the ~ClickException.show()~ method on it to display it and then exit the program with ~ClickException.exit_code~.
#+END_QUOTE

- ~UsageError~
- ~BadParameter~
- ~FileError~
** Support auto complete
- To support auto complete of ~yhy~ command in ~bash~, put the following line to your rc file.
#+BEGIN_SRC shell
  eval "$(_YHY_COMPLETE=source yhy)"
#+END_SRC

- For ~zsh~:
#+BEGIN_SRC shell
  autoload bashcompinit
  bashcompinit
  eval "$(_YHY_COMPLETE=source yhy)"
#+END_SRC

:REFERENCES:
- http://click.pocoo.org/5/bashcomplete/
- https://github.com/pallets/click/issues/323
:END:
{'fraction_non_alphanumeric': 0.18324549846288976, 'fraction_numerical': 0.006368028107158542, 'mean_word_length': 4.299011052937755, 'pattern_counts': {'":': 0, '<': 3, '<?xml version=': 0, '>': 3, 'https://': 3, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '627908', 'n_tokens_mistral': 3359, 'n_tokens_neox': 3267, 'n_words': 743}