標籤: pip

Python command line

最近為了想上手Python，所以想說用Python寫個簡易的cli 工具當作目標來當練習；這次就來記錄怎麼一步一步的寫出這個cli程式。
程式的需求，是希望可以設定一個定期備份wordpress 內容的服務，並且在備份完了以後，可以上傳到指定的AWS s3.

Requirements

  • 提供flag 可以讓使用者指定要備份的資料夾
  • 提供flag 可以讓使用者指定要上傳的s3 路徑
  • 備份的資料夾必須先經過壓縮後，才會上傳到s3

Dependencies

  • Python 3+
  • Poetry
  • Pip

Poetry 是目前主流的Python套件管理工具，而這次這個repo主要就是使用poetry來管理其相依的library。

Implementation

Cli flags

Config flags 的部分，主要是透過Click這個套件來實作。這個套件在使用上相當容易上手，透過decorator的方式就可以指定程式在執行時，需要帶入哪些指令。

像是下面這段程式碼，就指定了程式在執行時，需要帶入-s 或 --s3_path 作為s3 的路徑；即使我現在還不是很熟decorator，也可以輕易的讓程式支援flag。

@click.command()
@click.option(
     "-s",
     "--s3_path",
     default="",
     envvar="S3_PATH",
     help="The s3 path for uploading. (e.g. s3://path/to/upload )",
     required=True
 )

Entrypoint

除了讓程式支援flag，我們這邊也需要設定程式在執行時的進入點，通常會是一個自定義的function，其參數會是我們先前所設定的flags。

以下面的程式碼為例，我們指定了cli() 作為我們的這個程式的進入點，並且程式必須有2個參數，分別是input與s3_path。(參數的名稱必須與@click.option中的一致)

def cli(input, s3_path):
     if s3_path.find("s3://") != 0:
         logging.error("incorrect s3 path format")
         exit(1)

if name == "main":
    cli()

Config Poetry cli entrypoint

透過先前的設定，我們已經可以透過一般python 的執行方式(python cli.py)來執行我們的程式了，但為了讓我們的cli程式在執行時可以更像一個執行檔，我們可以透過Poetry來包裝我們的程式，這樣就不需要透過pyhton xxx.py的方式執行了!

Poetry entrypoint function

首先，我們必須先變動我們的程式路徑，並且指定一個可以當進入點的function，這邊我們就可以設定一個新的main()，而其function body就是執行我們先前的cli()

def main():
     cli()

接下來，我們必須在project 根資料夾下，新增一個子資料夾，並且把我們的cli.py移至這個子資料夾下，新的路徑結構為下

backup_to_s3_repo/
  poetry.lock
  pyproject.toml
  README.md
  backup_to_s3/
    __init__.py
    cli.py

Poetry entrypoint configuration

在這邊還需要在設定pyproject.toml，主要是為了讓poetry在執行時，可以用”alias”的方式來執行我們的程式，相關的pyproject.toml的內容如下：

下面的設定，可以讓我們執行poetry run backup_to_s3時，實際上去執行backup_to_s3/cli.py中的main()

[tool.poetry.scripts]
 backup_to_s3 = "backup_to_s3.cli:main"

Build and install

在完成前面所提到的設定之後，我們已經可以透過python backup_to_s3/cli.py 或poetry run backup_to_s3來執行我們的程式了；但為了讓我們的程式可以更像一般的系統預設的執行程，我們可以透過下面列出的方式來實作。

Build the poetry project

透過poetry build，poetry 會幫我們把整個poetry project與相關的套件封裝成一個tar.gz 檔，並儲存於dist/資料夾下。

在整個封裝的過程中，poetry會幫我們建立對應的.whl 與setup.py檔，以便於我們發佈或分享這個tar.gz 檔。

Install poetry build file by pip

在有了上述的tar.gz檔以後，我們就可以透過pip install的方式，將整個backup_to_s3程式安裝成像系統內建的指令程式了，詳細的指令可以參考下面

pip install dist/backup_to_s3-0.1.0.tar.gz

最後，完整的source code 可以參考這裡：
https://github.com/bamoo456/backup-to-s3

Reference