Komanda sətri tətbiqləri: argparse və click

`sys.argv` və onun məhdudiyyətləri; `argparse`: mövqe və adlı arqumentlər, tiplər, `choices`, susmaya görə dəyərlər, bayraqlar, `nargs`/`count`/`append`, kömək mətni və xətalar, alt əmrlər, çıxış kodları və `main(argv)`; dekoratorlarla `click`, qruplar və `CliRunner` ilə testlər.

  • İrəli
  • 22 dəq
  • 12 sual
  • 66 dərsdən 34-cüsü

Bu dərsdə öyrənəcəksən

  • Proqramın arqumentləri sys.argv ilə necə aldığını və onları əl ilə təhlil etməyin niyə kövrək olduğunu izah etmək
  • argparse ilə komanda sətrini təsvir etmək: mövqe və adlı arqumentlər, tiplər, seçimlər, bayraqlar, alt əmrlər
  • main(argv)-dan düzgün çıxış kodları qaytarmaq və CLI-ni siyahı ötürərək yoxlamaq
  • Eyni aləti click ilə yazmaq və CliRunner ilə test etmək

Aysel valyuta çevirmək üçün skript yazıb. Həmkarları hər dəfə kodu açıb AMOUNT = 100 və RATE = 1.7 sətirlərini dəyişirlər — gec-tez kimsə səhv sətri pozacaq. Əgər skript parametrləri komanda sətrindən qəbul etsə, python convert.py 100 USD --rate 1.7 yazmaq kifayətdir, --help isə nə etmək lazım olduğunu özü izah edir. «Avtomatlaşdırma skriptləri» dərsində argparse ilə qısa tanış oldun; indi onu dərindən öyrənəcək, sonra eyni aləti məşhur click kitabxanası ilə yazacağıq.

sys.argv: arqumentlər sətirlər siyahısı kimi

Terminalda yazılan hər söz proqrama sys.argv siyahısında çatır: sys.argv[0] skriptin adıdır, qalanları isə arqumentlərdir — həmişə sətir. Əl ilə təhlil tez kövrəkləşir: arqument unudulanda IndexError, səhv tipdə dəyər olanda anlaşılmaz Traceback, kömək mətni yoxdur, --rate kimi adlı parametrləri isə hər dəfə özün axtarmalısan.

Python
import sys

print(sys.argv)
name = sys.argv[1] if len(sys.argv) > 1 else 'world'
times = int(sys.argv[2]) if len(sys.argv) > 2 else 1
for _ in range(times):
    print(f'Hello, {name}!')
greet.py
Terminal
$ python greet.py Aysel 2
['greet.py', 'Aysel', '2']
Hello, Aysel!
Hello, Aysel!
$ python greet.py
['greet.py']
Hello, world!
$ python greet.py Aysel two
['greet.py', 'Aysel', 'two']
Traceback (most recent call last):
  ...
ValueError: invalid literal for int() with base 10: 'two'
'2' sətir kimi gəlir və int() ilə çevrilməlidir; two yazılanda istifadəçi xəta mesajı əvəzinə proqramçı üçün olan Traceback görür (burada qısaldılıb).

Davamını oxumaq üçün pulsuz qeydiyyatdan keç

Dərsin qalan bölmələri, test və qeydlər Educora hesabı ilə açılır. Qeydiyyat bir dəqiqə çəkir; irəliləyişin bütün cihazlarında saxlanılır.

argparse: mövqe və adlı arqumentlər

Mövqe arqumenti, seçim və bayraqTərif

Mövqe arqumenti yeri ilə tanınır və adətən mütləqdir: convert 100 USD. Seçim (adlı arqument) - və ya -- ilə başlayır, istənilən sırada yazılır və susmaya görə dəyəri olur: --rate 1.7, qısa forması -r 1.7. Bayraq dəyərsiz seçimdir: --verbose yazılıbsa True, yazılmayıbsa False.

add_argument parametriNə edir
type=int, type=floatsətri tipə çevirir; alınmasa, aydın xəta verir
default=...arqument verilmədikdə dəyər
choices=['USD', 'EUR']yalnız bu dəyərlərə icazə verir
action='store_true'bayraq: True/False
action='count', action='append'-vvv → 3; təkrarlanan seçimi siyahıya yığır
nargs='?', '*', '+'0 və ya 1, istənilən sayda, ən azı 1 dəyər
help=, metavar=--help mətni və orada göstərilən ad

Real skriptdə parser.parse_args() arqumentsiz çağırılır və sys.argv[1:]-i oxuyur. Ona siyahı ötürsək, eyni kod brauzerdə və testlərdə də işləyir — aşağıdakı bütün nümunələr belədir. Nəticə Namespace obyektidir: hər arqument onun atributudur, --dry-run kimi adlarda tire alt xəttə çevrilir (args.dry_run).

Python
import argparse

parser = argparse.ArgumentParser(prog='convert', description='Convert AZN to another currency.')
parser.add_argument('amount', type=float, help='amount in AZN')
parser.add_argument('currency', choices=['USD', 'EUR', 'TRY'], help='target currency')
parser.add_argument('-r', '--rate', type=float, default=1.7, help='AZN per unit')
parser.add_argument('--digits', type=int, default=2, metavar='N', help='digits after the point')
parser.add_argument('-v', '--verbose', action='store_true', help='also print the formula')

args = parser.parse_args(['100', 'USD', '--rate', '1.7', '-v'])
print(args)
if args.verbose:
    print(f'{args.amount} / {args.rate}')
print(f'{args.amount} AZN = {round(args.amount / args.rate, args.digits)} {args.currency}')
print(parser.parse_args(['50', 'EUR', '-r', '1.95', '--digits', '1']))
Gözlənilən nəticə
Namespace(amount=100.0, currency='USD', rate=1.7, digits=2, verbose=True)
100.0 / 1.7
100.0 AZN = 58.82 USD
Namespace(amount=50.0, currency='EUR', rate=1.95, digits=1, verbose=False)
'100' avtomatik 100.0 oldu, -v bayrağı verbose=True verdi. İkinci çağırışda verilməyən seçimlər susmaya görə dəyərlərini aldı.
Python
import argparse

parser = argparse.ArgumentParser(prog='backup')
parser.add_argument('folders', nargs='+', help='one or more folders')
parser.add_argument('-x', '--exclude', action='append', default=[], help='a pattern to skip (repeatable)')
parser.add_argument('-v', '--verbose', action='count', default=0, help='-v, -vv, -vvv')
group = parser.add_mutually_exclusive_group()
group.add_argument('--zip', action='store_true')
group.add_argument('--tar', action='store_true')

print(parser.parse_args(['docs', 'photos', '-x', '*.tmp', '-x', '*.log', '-vv', '--zip']))
print(parser.parse_args(['docs']))
Gözlənilən nəticə
Namespace(folders=['docs', 'photos'], exclude=['*.tmp', '*.log'], verbose=2, zip=True, tar=False)
Namespace(folders=['docs'], exclude=[], verbose=0, zip=False, tar=False)
nargs='+' bir neçə qovluğu siyahıya yığdı, təkrarlanan -x append ilə siyahı oldu, -vv isə 2 saydı. add_mutually_exclusive_group --zip və --tar-ın birlikdə yazılmasına icazə vermir.

Nümunələr: argparse qaydaları

Məsələ

1) --dry-run seçimi Namespace-də hansı ada sahib olur?
2) action='count', default=0 ilə -vvv nə verir?
3) add_argument('output', nargs='?', default='out.txt') və parse_args([]) — args.output nədir?

Həllini göstərHəllini gizlət

Həll

1) dry_run — baş tirelər atılır, ortadakı tire alt xəttə çevrilir.
2) 3 — hər v sayğacı 1 artırır.
3) 'out.txt' — nargs='?' mövqe arqumentini istəyə bağlı edir və dəyər olmayanda default götürülür.

Kömək mətni və xətalar

argparse -h/--help seçimini özü əlavə edir və kömək mətnini description ilə help= mətnlərindən qurur; %(default)s susmaya görə dəyəri yerinə qoyur. İstifadəçi səhv edəndə argparse qısa usage sətrini və aydın mesajı stderr-ə yazır və proqramı 2 kodu ilə dayandırır (SystemExit atır). Testdə və brauzerdə bunu except SystemExit ilə tutmaq olar.

Python
import argparse

parser = argparse.ArgumentParser(prog='convert', description='Convert AZN to another currency.')
parser.add_argument('amount', type=float, help='amount in AZN')
parser.add_argument('currency', choices=['USD', 'EUR', 'TRY'], help='target currency')
parser.add_argument('-r', '--rate', type=float, default=1.7, help='AZN per unit (default: %(default)s)')
parser.add_argument('-v', '--verbose', action='store_true', help='also print the formula')
parser.print_help()
Gözlənilən nəticə
usage: convert [-h] [-r RATE] [-v] amount {USD,EUR,TRY}

Convert AZN to another currency.

positional arguments:
  amount           amount in AZN
  {USD,EUR,TRY}    target currency

options:
  -h, --help       show this help message and exit
  -r, --rate RATE  AZN per unit (default: 1.7)
  -v, --verbose    also print the formula
Python
import argparse
import contextlib
import sys

parser = argparse.ArgumentParser(prog='convert')
parser.add_argument('amount', type=float)
parser.add_argument('currency', choices=['USD', 'EUR', 'TRY'])


def run(argv):
    with contextlib.redirect_stderr(sys.stdout):      # show the error text in the output
        try:
            print(parser.parse_args(argv))
        except SystemExit as e:
            print('exit code:', e.code)


run(['100', 'USD'])
run(['100', 'GBP'])
run(['ten', 'USD'])
run(['100'])
Gözlənilən nəticə
Namespace(amount=100.0, currency='USD')
usage: convert [-h] amount {USD,EUR,TRY}
convert: error: argument currency: invalid choice: 'GBP' (choose from USD, EUR, TRY)
exit code: 2
usage: convert [-h] amount {USD,EUR,TRY}
convert: error: argument amount: invalid float value: 'ten'
exit code: 2
usage: convert [-h] amount {USD,EUR,TRY}
convert: error: the following arguments are required: currency
exit code: 2
redirect_stderr(sys.stdout) xəta mətnini adi çıxışa yönəldir ki, burada görünsün. Mesajların dəqiq sözləri Python versiyaları arasında bir az fərqlənə bilər, kod isə həmişə 2-dir.

Alt əmrlər və çıxış kodları: mini-layihə

Böyük alətlərin alt əmrləri olur: git commit, git push, pip install. argparse-da bunu add_subparsers(dest='command', required=True) edir: hər alt əmr öz arqumentləri olan ayrıca parserdir, seçilən əmrin adı isə args.command-a yazılır. Kiçik qeydlər aləti quraq: add, list və done əmrləri, qeydlər notes.json faylında saxlanır.

Çıxış koduTərif

Proqram bitəndə əməliyyat sisteminə qaytardığı ədəd: 0 — uğur, sıfırdan fərqli — xəta (argparse səhv arqumentlər üçün 2 işlədir). Skriptlər, planlaşdırıcılar və CI sistemləri məhz bu koda baxır: bash-da cmd1 && cmd2 ikinci əmri yalnız birinci 0 qaytaranda işə salır, son kodu bash-da $?, PowerShell-də $LASTEXITCODE göstərir. Python-da sys.exit(kod) ilə qaytarılır.

Python
import argparse
import contextlib
import json
import shlex
import sys
from pathlib import Path

DB = Path('notes.json')


def main(argv=None):
    parser = argparse.ArgumentParser(prog='notes')
    sub = parser.add_subparsers(dest='command', required=True)
    add = sub.add_parser('add', help='add a note')
    add.add_argument('text')
    add.add_argument('-p', '--priority', type=int, choices=[1, 2, 3], default=2)
    sub.add_parser('list', help='show open notes').add_argument('--all', action='store_true')
    sub.add_parser('done', help='mark a note as done').add_argument('number', type=int)
    args = parser.parse_args(argv)

    notes = json.loads(DB.read_text(encoding='utf-8')) if DB.exists() else []
    if args.command == 'add':
        notes.append({'text': args.text, 'priority': args.priority, 'done': False})
        print(f'added #{len(notes)}')
    elif args.command == 'list':
        for i, n in enumerate(notes, start=1):
            if args.all or not n['done']:
                print(f"{i}. [{'x' if n['done'] else ' '}] p{n['priority']} {n['text']}")
    elif not 1 <= args.number <= len(notes):
        print(f'notes: no note #{args.number}', file=sys.stderr)
        return 1
    else:
        notes[args.number - 1]['done'] = True
    DB.write_text(json.dumps(notes), encoding='utf-8')
    return 0


with contextlib.redirect_stderr(sys.stdout):
    for argv in (['add', 'Buy bread'], ['add', 'Python homework', '-p', '1'],
                 ['done', '1'], ['list'], ['list', '--all'], ['done', '7']):
        print('$ notes', shlex.join(argv))
        print('  exit code', main(argv))
Gözlənilən nəticə
$ notes add 'Buy bread'
added #1
  exit code 0
$ notes add 'Python homework' -p 1
added #2
  exit code 0
$ notes done 1
  exit code 0
$ notes list
2. [ ] p1 Python homework
  exit code 0
$ notes list --all
1. [x] p2 Buy bread
2. [ ] p1 Python homework
  exit code 0
$ notes done 7
notes: no note #7
  exit code 1
main(argv) çıxış kodunu qaytarır, sys.exit çağırmır — ona görə onu testdə və ya burada bir neçə dəfə çağırmaq olur. Səhv nömrə üçün mesaj stderr-ə gedir və kod 1 olur. shlex.join arqumentləri terminalda yazıldığı kimi dırnaqlarla göstərir.
Terminal
$ python notes.py add "Buy bread"
added #1
$ python notes.py done 7
notes: no note #7
$ echo $?
1
$ python notes.py remove 1
usage: notes [-h] {add,list,done} ...
notes: error: argument command: invalid choice: 'remove' (choose from add, list, done)
$ echo $?
2
$ python notes.py list && echo "all good"
1. [ ] p2 Buy bread
all good
Eyni kod faylda: sonuna if __name__ == '__main__': sys.exit(main()) əlavə olunub. remove əmri olmadığı üçün argparse 2 kodu ilə çıxdı, && isə list uğurla bitdiyi üçün echo-nu işə saldı.

Əmrlər çoxalanda if/elif zənciri uzanır. Onda hər alt əmr üçün ayrıca funksiya yazıb onu set_defaults(func=cmd_add) ilə öz parserinə bağlamaq olar, main isə sadəcə return args.func(args) çağırır. Bir də fikir ver: nəticələr stdout-a, səhv mesajları isə print(..., file=sys.stderr) ilə stderr-ə gedir. İstifadəçi python notes.py list > notes.txt yazanda faylda yalnız qeydlər olur, xəta isə ekranda qalır.

click: eyni iş dekoratorlarla

click üçüncü tərəf kitabxanadır (pip install click); məsələn, Flask-ın flask əmri onun üzərində qurulub. Parser obyekti əvəzinə funksiyanın üstünə dekoratorlar yazılır (bax: «Dekoratorlar və qapanmalar»): @click.command(), mövqe arqumentləri üçün @click.argument, seçimlər üçün @click.option. Arqumentlər funksiyaya adi parametrlər kimi gəlir, funksiyanın docstring-i kömək mətni olur. click.Choice, click.IntRange, is_flag=True, show_default=True və mühit dəyişənindən dəyər götürən envvar= hazırdır; alt əmrləri @click.group() qurur.

Python
import click


@click.command()
@click.argument('amount', type=float)
@click.argument('currency', type=click.Choice(['USD', 'EUR', 'TRY']))
@click.option('-r', '--rate', type=float, default=1.7, show_default=True, help='AZN per unit.')
@click.option('-v', '--verbose', is_flag=True, help='Also print the formula.')
def convert(amount, currency, rate, verbose):
    """Convert AZN to another currency."""
    if verbose:
        click.echo(f'{amount} / {rate}')
    click.echo(f'{amount} AZN = {round(amount / rate, 2)} {currency}')


if __name__ == '__main__':
    convert()
convert.py
Terminal
$ python convert.py 100 USD -v
100.0 / 1.7
100.0 AZN = 58.82 USD
$ python convert.py --help
Usage: convert.py [OPTIONS] AMOUNT {USD|EUR|TRY}

  Convert AZN to another currency.

Options:
  -r, --rate FLOAT  AZN per unit.  [default: 1.7]
  -v, --verbose     Also print the formula.
  --help            Show this message and exit.
$ python convert.py 100 GBP
Usage: convert.py [OPTIONS] AMOUNT {USD|EUR|TRY}
Try 'convert.py --help' for help.

Error: Invalid value for '{USD|EUR|TRY}': 'GBP' is not one of 'USD', 'EUR', 'TRY'.
click 8.5 ilə yoxlanılıb. Kömək mətnində docstring və [default: 1.7] göründü, səhv dəyər üçün isə click 2 kodu ilə çıxır.

click-in güclü tərəfi testlərdir: click.testing.CliRunner əmri ayrıca proses açmadan çağırır, çıxışı və kodu tutur. Testləri «pytest ilə testləşdirmə» dərsindəki kimi yazırıq:

Python
import click
from click.testing import CliRunner


@click.group()
def cli():
    """A tiny notes tool."""


@cli.command()
@click.argument('text')
@click.option('-p', '--priority', type=click.IntRange(1, 3), default=2, show_default=True)
def add(text, priority):
    """Add a note."""
    click.echo(f'added: {text} (p{priority})')


def test_add():
    result = CliRunner().invoke(cli, ['add', 'Buy bread', '-p', '1'])
    assert result.exit_code == 0
    assert result.output == 'added: Buy bread (p1)\n'


def test_bad_priority():
    result = CliRunner().invoke(cli, ['add', 'Buy bread', '-p', '9'])
    assert result.exit_code == 2
    assert '9 is not in the range 1<=x<=3' in result.output
test_notes_cli.py
Terminal
$ pytest -q test_notes_cli.py
..                                                                       [100%]
2 passed in 0.05s
IntRange(1, 3) 9-u rədd etdi; result.output səhv mesajını da saxlayır. Vaxt (0.05s) hər işə salınmada fərqli olur.
argparseclick
Quraşdırmastandart kitabxanapip install click
Üslubparser obyekti, add_argumentfunksiya üstündə dekoratorlar
Alt əmrləradd_subparsers@click.group()
Testmain([...]) çağırmaqCliRunner().invoke(...)
Əlavələr—sorğular (prompt), rənglər, envvar
Asılılıq istəməyən kiçik skript üçün argparse, çoxlu əmrli böyük alət üçün çox vaxt click seçilir.

Tapşırıq

resize parserinə arqumentlər əlavə et: mövqe arqumenti image, -w/--width (tam ədəd, susmaya görə 800), bayraq --keep-ratio və --format (jpg, png, webp, susmaya görə jpg).

Tapşırıq · Python
import argparse

parser = argparse.ArgumentParser(prog='resize')
# add: the positional argument image; -w/--width (int, default 800);
# the flag --keep-ratio; --format with choices jpg, png, webp (default jpg)

args = parser.parse_args(['photo.png', '-w', '1200', '--keep-ratio'])
print(args.image, args.width, args.keep_ratio, args.format)
args = parser.parse_args(['logo.png', '--format', 'webp'])
print(args.image, args.width, args.keep_ratio, args.format)
Gözlənilən nəticə
photo.png 1200 True jpg
logo.png 800 False webp

Tapşırıq

wordcount alətini tamamla: --top N (susmaya görə 3) neçə söz göstəriləcəyini, -i/--ignore-case bayrağı isə sözlərin kiçik hərfə salınıb sayılmasını təyin etsin.

Tapşırıq · Python
import argparse
from collections import Counter


def main(argv):
    parser = argparse.ArgumentParser(prog='wordcount')
    parser.add_argument('text')
    # add --top (int, default 3) and the flag -i/--ignore-case
    args = parser.parse_args(argv)
    words = args.text.split()
    # with --ignore-case, lowercase every word
    for word, n in Counter(words).most_common(3):
        print(word, n)
    return 0


main(['Tea tea coffee Tea milk coffee', '--top', '2'])
print('---')
main(['Tea tea coffee Tea milk coffee', '-i'])
Gözlənilən nəticə
Tea 2
coffee 2
---
tea 3
coffee 2
milk 1

Yadda saxla

  • sys.argv — sətirlər siyahısıdır ([0] skriptin adı); əl ilə təhlil kövrəkdir, argparse tipləri, kömək mətnini və xətaları özü həll edir.
  • Mövqe arqumentləri mütləqdir, seçimlər --ad ilə yazılır və susmaya görə dəyəri olur; type, choices, store_true, count, append, nargs.
  • Səhv arqumentdə argparse stderr-ə yazır və 2 kodu ilə çıxır; testdə və brauzerdə parse_args-a siyahı ötür.
  • Alt əmrlər: add_subparsers; main(argv=None) kodu qaytarsın, sys.exit(main()) onu sistemə versin: 0 — uğur.
  • click eyni işi dekoratorlarla görür (command, argument, option, group) və CliRunner ilə asan test olunur.
Dərsdə səhv və ya qeyri-dəqiqlik gördün?

Özünü yoxla

12 sual. Hər düzgün cavab XP qazandırır.

Sual 1 / 12

Sual 1 / 12. python greet.py Aysel 2 işə salınanda sys.argv nəyə bərabərdir?