Python | Democratizing Data

Scrape Notion and convert into PDF

Fri, 26 Jan 2024 18:40:00 -0700

I love VanGohan, who is a Japanese meal kits provider in Vancouver. Their meal kits are really tasty and authentic Japanese foods. I can’t live without them. When I visited Japan last year, I wasn’t too eager to find nice Japanese restaurants because of them.

Recipe on Notion is good, if it’s printable

They provide a recipe on Notion. Seeing the recipes on it is great since they can fix recipes quite quickly.

However, there’s one caveat of Notion. They don’t provide printable pages. It’s super annoying to copy and past the recipes to the memo app, and print it out. I asked Notion’s support team, but they answered it isn’t a prioritized item implicitly.

Ok, it’s automation time!

Scrape Notion with Python

As my handy tool, I have been using Python for this kind of automation for years. Originally, I used beautifulsoup, which is great package for web scraping, but I gave it up to use it. Contents of Notion is rendered by JavaScript dynamically.

I chose Selenium and it works like a charm.

Here is the GitHub repository:

They key takeaways are:

chromedriver-autoinstaller package is useful to avoid extra efforts of Chrome driver installation.
Selenium is easy enough to export PDF code.
Running the script on GitHub Actions is easy. Don’t forget to install fonts if it’s not English page.

Originally, I thought I had to prepare a Docker image, but I was aware it was not mandatory. Managing a Docker image for this kind of hobby script would be costly. So, I’m going to keep this approach and will look back if it is the right way.

Currently, I scheduled the GitHub Actions workflow. It will update the PDFs on the repository automatically.

https://github.com/chezou/vangohan-pdf/tree/main/docs

Edit: Now I use Cloudflare Pages to host the PDFs. You can check at https://vangohan.chezo.uno/.

No Python environment on a local machine is needed anymore.

Yay, automation is completed! 😁

tabula-py 2.8.0 now uses jpype to launch JVM

Sat, 09 Sep 2023 17:13:08 -0700

Recently, I released tabula-py 2.8.0. It is a major release because it uses jpype to launch JVM. This means that it reduces JVM launch time since jpype reuse JVM via JNI.

How fast is it?

I measured read_pdf_with_template function execution time, which repeatedly launches Java process in the previous version.

The example template contains 4 rules, which means it calls tabula-java 4 times.

$ cat examples/data.tabula-template.json | jq
[
 {
 "page": 1,
 "extraction_method": "guess",
 "x1": 153.99985500000003,
 "x2": 565.5698550000001,
 "y1": 123.999615,
 "y2": 531.7446150000001,
 "width": 411.57,
 "height": 407.745
 },
 {
 "page": 2,
 "extraction_method": "guess",
 "x1": 153.99985500000003,
 "x2": 453.879855,
 "y1": 123.99884999999993,
 "y2": 210.44384999999994,
 "width": 299.88,
 "height": 86.44500000000001
 },
 {
 "page": 2,
 "extraction_method": "guess",
 "x1": 153.99985500000003,
 "x2": 487.53985500000005,
 "y1": 410.99625000000003,
 "y2": 497.44125,
 "width": 333.54,
 "height": 86.44500000000001
 },
 {
 "page": 3,
 "extraction_method": "guess",
 "x1": 153.99985500000003,
 "x2": 235.85485500000001,
 "y1": 123.99885000000012,
 "y2": 322.8988500000001,
 "width": 81.855,
 "height": 198.9
 }

The result is as follows:

v2.7.0:

$ python -m timeit 'import tabula; tabula.read_pdf_with_template("examples/data.pdf", "examples/data.tabula-template.json")' 2> /dev/null
1 loop, best of 5: 1.31 sec per loop

v2.8.0:

$ python -m timeit 'import tabula; tabula.read_pdf_with_template("examples/data.pdf", "examples/data.tabula-template.json")' 2> /dev/null
1 loop, best of 5: 75 msec per loop

It is 17 times faster than the previous version!

Caveats

Since jpype doesn’t allow to reboot JVM, you can pass java_options for the first time only. If you want to change java_options, you need to restart Python process.

Challenges for releasing v2.8.0

I had to solve several challenges to release this version.

The test issue with different `java_options`

As I mentioned, jpype doesn’t allow to reboot JVM. This causes unit test with different java_options to fail. I solved this by separating run with nox session.

See https://github.com/chezou/tabula-py/pull/356/files#r1306600161 for details.

This limitation is not a big deal for tabula-py users because tabula-py users don’t need to change java_options frequently.

Read the docs default behavior change

Read the docs changed the default installation packages for Sphinx. I didn’t declared the dependency for Sphinx, so it caused the build failure.

The default behavior of RTD was just installing the latest version of Sphinx and sphinx-rtd-theme, however, now it installs very old version of them like: https://github.com/readthedocs/readthedocs.org/issues/10670#issuecomment-1694761746

I solved this by pinning the versions of dependency for Sphinx and sphinx-rtd-theme.

4 Steps to Release a CLI in Python

Fri, 20 May 2022 23:32:41 -0700

This is what I learned from creating a Python CLI (digdaglog2sql) in a day.

In just 4 steps, you can release a CLI written in Python easily.

Create a project by using poetry

Poetry is a modern Python packaging and dependency management tool. Poetry is becoming popular and defacto rapidly.

By using Poetry, it enables us to manage package dependency, to create a project template, and to publish to PyPI.

To setup a project with Poetry, this article is the best to read even if you build a CLI.

https://future--architect-github-io.translate.goog/articles/20210611a/?_x_tr_sl=auto&_x_tr_tl=en&_x_tr_hl=ja&_x_tr_pto=wapp (originally written in Japanese)

One thing I added to my project is isort. isort is to sort imports automatically.

Here is the example of my project.

[tool.taskipy.tasks]
test = { cmd = "pytest tests", help = "runs all unit tests" }
pr_test = "task lint"
fmt = { cmd = "black tests digdaglog2sql && isort digdaglog2sql tests", help = "format code" }
lint = { cmd = "task lint_black && task lint_flake8 && task lint_isort && task lint_mypy", help = "exec lint" }
lint_flake8 = "flake8 --max-line-length=88 tests digdaglog2sql"
lint_mypy = "mypy tests digdaglog2sql"
lint_black = "black --check tests digdaglog2sql"
lint_isort = "isort digdaglog2sql tests --check-only"

Create a CLI with Click/Cloup

Click is a famous Python package to build a command line tool. You can easily create a CLI by using decorator.

Here is the example from the Click website:

import click

@click.command()
@click.option("--count", default=1, help="Number of greetings.")
@click.option("--name", prompt="Your name",
 help="The person to greet.")
def hello(count, name):
 """Simple program that greets NAME for a total of COUNT times."""
 for _ in range(count):
 click.echo("Hello, %s!" % name)

if __name__ == '__main__':
 hello()

Cloup is an extension of Click.

Using by Cloup, you can handle option groups and complex constraints like mutually_exclusive as:

@option_group(
 "Cool options",
 option('--foo', help='This text should describe the option --foo.'),
 option('--bar', help='This text should describe the option --bar.'),
 constraint=mutually_exclusive,
)

Constraints of Cloup can validate the dependency and it also renders constraints in help.

Use poetry-dynamic-versioning for version management

poetry-dynamic-versioning is a Python package to do same thing as setuptools-scm. You don’t need to write version number by hand since this package use the version from tag of Git, e.g., “v.0.1.0”.

Managing version by Git enables you to release to PyPI from GitHub Actions. This means you can release to PyPI on mobile device by releasing from GitHub.

After installation of poetry-dynamic-versioning, you just add three thing in pyproject.toml:

[tool.poetry]
version = "0.0.0"

[tool.poetry-dynamic-versioning]
enable = true

[build-system]
requires = ["poetry-core>=1.0.0", "poetry-dynamic-versioning"]
build-backend = "poetry.core.masonry.api"

Note that build-system configuration may vary depending on how you install poetry-dynamic-versioning. See the document for detail.

Introduce GitHub Actions to release the package to PyPI

As I mentioned above, I highly recommend to use GitHub Actions to release a Package to PyPI.

Since GitHub provides Release notes generation feature now, creating a release from GitHub with triggering PyPI release is the best way to publish a new version.

Here is the snippet of GH Actions to release to PyPI by using poetry.

name: Upload Python Package

on:
 release:
 types: [created]

permissions:
 contents: read

jobs:
 deploy:

 runs-on: ubuntu-latest

 steps:
 - uses: actions/checkout@v3

 steps:
 - uses: actions/checkout@v3
 - name: Set up Python
 uses: actions/setup-python@v3
 with:
 python-version: '3.x'
 - name: Install dependencies
 run: |
 python -m pip install --upgrade pip
 pip install poetry
 - name: Build and publish package
 run: |
 poetry version $(git describe --tags --abbrev=0)
 poetry build
 poetry publish --username __token__ --password ${{ secrets.PYPI_API_TOKEN }}

Note that, while PyPI API Token can be found on PyPI, if you need to create project scope token, you need to upload a package manually first.

py> operator development guide for Python users

Thu, 05 Mar 2020 14:15:52 +0000

How to build & test custom scripts on local env before pushing

General strategy:

Make a Python task reasonable granularity to run on local env

Since Treasure Workflow doesn’t have intermediate storage between tasks, a task can be huge. Considering container launch time, it would be better to create a single huge task, but it makes difficult for debugging. Starting from creating a reasonable size of function which is able to debug easily. Then, you can create a function that calls those minimal functions at once.

There are few options to develop py> operator on the local environment.

Use TD docker image
Create a Python virtual environment on local env

1. Use TD docker image

To develop a single py> operator task, you can use the official docker image to run python tasks locally. Like ordinal Python script, you can add the main guard like:

if __name__ == "__main__":
 your_function("default_argument")

As of Mar. 5, 2020, our latest official images are shown as the following:

digdag/digdag-python:3.7
digdag/digdag-anaconda3:2019.03

If you want to run a debugger toward Docker container, we recommend using PyCharm to run a remote debugger. See also .

2. Create a Python virtual environment on local env

Python provides venv to create virtual environments, you can create the same environment by using pip.

Download requirements.txt and constraints.txt from and you can install dependencies as same environment with digdag-python:3.7 as:

$ python -m venv .venv
$ source .venv/bin/activate
(.venv)$ pip install -r requirements.txt -c constraints.txt`

Using this virtual environment, you can develop by using the same packages on the local environment.

Note that this approach can’t ensure OS differences, which means the production environment is running on Debian but the development environment might be Windows/macOS X. This causes errors when executing OS-dependent commands like apt-get.

If you want to create the same environment with anaconda image, you can download environment.yml from , and run:

conda env update -n base -f environment.yml

Now you have the same Python packages with digdag/digdag-anaconda3:2019.03

Note that this command will overwrite existing conda environment, we highly recommend to modify name in environment.yml from base to your environment name like my-env, and run:

conda env create -f environment.yml

Test a workflow including Python

If you want to run an entire workflow on the local environment, ~~you can use~~ .

As of Mar 5, 2020, Treasure Data uses digdag v0_10 branch, but it may change in the near future.

As of Feb 14, 2021, Treasure Data moved to v0_11 branch. You may use the latest release branch. https://github.com/treasure-data/digdag/pull/1502 https://github.com/treasure-data/digdag/pull/1504

Passing Parameters to py> operator

There are two ways to pass parameters into py> operator:

ordinal digdag argument
environment variable
digdag variable

1. digdag argument

Assuming we have a Python script named py_scripts/examples.py like:

def print_arg(msg):
 print(f"Message is {msg}")

Passing msg argument from simple_with_arg task can be like:

+simple_with_arg:
 py>: py_scripts.examples.print_arg
 msg: "Hello World"
 docker:
 image: "digdag/digdag-python:3.7"

If you want to pass multiple arguments, you can add arguments in your function, then add them into digdag arguments as well.

Note that digdag arguments can be passed into Python seamlessly so that you might face unintended variables passed by using keyword arguments **kwargs.

For example, in this case, docker variable can be passed as a dictionary {“image”: “digdag/digdag-python:3.7”}. We recommend having implicit arguments on a Python function.

Note that there might be unintended conflicts between digdag and py> operator. Assuming you set some digdag variables like the following:

_export:
 td:
 database: my_db

+simple_with_arg2:
 py>: py_scripts.examples.print_arg_td
 msg: "Hello World"
 docker:
 image: "digdag/digdag-python:3.7"

having python function print_arg_td with td argument like the following:

def print_arg_td(msg, td=None):
 print(f"'msg' is {msg} and 'td' is {td}")

In this case, td variable never can be None since exported td variable, i.e., {“database”: “my_db”} always should be passed. This may cause type mismatches like dictionary and string. We recommend avoiding to use preserved arguments for digdag, like td variables like:

td.endpoint
td.apikey
td.use_ssl
td.proxy.enabled
td.proxy.host
td.proxy.port
td.proxy.password
td.proxy.user

Note that these variables might be changed in the future. There are build-in digdag variables. See digdag build-in variables at

Also, digdag might converts unintended type e.g., an integer from a string, so we recommend to evaluate or explicitly convert type on a Python function.

2. environment variable

Environment variables can be another option to pass parameters to py> operator. An environment variable is reasonable for passing secure information or secrets.

For example, if we have a task simple_with_env

+simple_with_env:
 py>: py_scripts.examples.print_env
 _env:
 MY_ENV_VAR: "hello"
 docker:
 image: "digdag/digdag-python:3.7"

This MY_ENV_VAR can be accessed by using os.environ like:

import os

def print_env():
 print(f'Env var is {os.environ["MY_ENV_VAR"]}')

Using an environment variable should be important especially when you need to use secrets information e.g. Treasure Data API key or AWS secrets key, etc.

digdag has a feature to store secrets information. Secrets are stored on digdag (or Treasure Workflow) database when executing td workflow secrets subcommand.

Assuming you’ve set a secret named td.apikey. This secret can be passed to py> operator like:

+simple_with_env2:
 py>: py_scripts.examples.access_td
 _env:
 TD_API_KEY: ${secret:td.apikey}
 docker: image: "digdag/digdag-python:3.7"

from py_scripts/examples.py like:

import os

def access_td():
 apikey = os.environ["TD_API_KEY"]
 # Do awesome execution

If you try to pass secrets from ordinal digdag arguments, secrets will never be fetched from secrets DB. For example, if you have a task like the following:

+simple_with_env_ng:
 py>: py_scripts.examples.access_td_ng
 apikey: ${secret:td.apikey}
 docker: image: "digdag/digdag-python:3.7"

by using the following script like:

def access_td_ng(apikey):
 print(apikey)
 # Always shows "${secret:td.apikey}" insted of actual API key like "1234/XXXX"

3. digdag variable

If you want to read digdag variable in a Python script, you can use digdag.env.params as the following:

def read_workflow_env(msg):
 import digdag
 print(digdag.env.params["my_msg"])

Note that import digdag can be run only when the script is run as a digdag py> operator task. If you want to avoid import error, you should write try-except syntax like:

try:
 import digdag
 digdag.env.store({"feature_query": feature_query})
except ImportError:
 pass

Directory structures

I recommend having the following directory structure.

my_project
├── README.md
├── config
│ ├── params.test.yml <- Configuration file for run through test. Mirror params.yml except for `td.database`
│ └── params.yml <- Configuration file for production
├── awesome_workflow.dig <- Main workflow to be executed
├── ingest.dig <- Data ingestion workflow
├── py_scripts <- Python scripts directory
│ ├── __init__.py
│ ├── data.py <- Script to upload data to Arm Treasure Data
│ └── my_script.py <- Main script to execute e.g. Data enrichment, ML training
├── queries <- SQL directory
│ └── example.sql
├── run_test.sh <- Test shell script for local run through test
└── test.dig <- Test workflow for local run through test

You can generate this structure from a template by using cookiecutter-digdag.

How to install Python packages / OS packages

For installation of Python packages, you can use os.syste or subprocess.run like:

import os, sys
os.system(f"{sys.executable} -m pip install --upgrade pytd==1.4.3")

import subprocess
# arguments should be passed by list
subprocess.run([sys.executable, "-m", "pip", "install", "--upgrade", "pytd==1.4.3"])

Ensure you set the version number of Python package.

To install OS packages, you can execute like the following:

import os
os.system("apt-get update") # Need to run before doing apt-get install
os.system("apt-get install -y wkhtmltopdf")

How to read/write tiny variables between digdag tasks

To read a digdag variable, you can use digdag.env.params as mentioned above.

To pass variables to another Python task, you can use import digdag.

def store_workflow_env(msg):
 import digdag
 digdag.env.store({"my_msg": msg})

This example code sets my_msg variable which is able to use the following tasks like:

+store_msg:
 py>: py_scripts.examples.store_workflow_env
 msg: "Hello World"
 docker:
 image: "digdag/digdag-python:3.7"

+restore_msg:
 echo>: ${my_msg}

Error notification with Python stack trace

digdag has _error: syntax to send a notification for an error message. You can access ${error.message} digdag variable to send the notification for Slack or Email.

Assuming that if we have the following workflow:

+simple_raise_error:
 py>: py_scripts.examples.error_sample
 docker:
 image: "digdag/digdag-python:3.7"

_error:
 echo>: ${error.message}

with this Python script:

def error_sample():
 int("a1234") # raises ValueError

This script always raises ValueError and the workflow log shows stack trace of Python as the following:

2019-12-24 23:06:32 +0900 [INFO] (0039@[0:python]+simple^error): echo>: Python command failed with code 1: invalid literal for int() with base 10: 'a1234' (ValueError)
 from Traceback (most recent call last):
 from File ".digdag/tmp/digdag-py-2-1815457087076518360/runner.py", line 165, in <module>
 result = callable_type(**args)
 from File "/private/var/folders/y9/bnjb3krn39s22rmg_wvlnf7m0000gp/T/digdag-tempdir2111531196420040503/workspace/1_simple_1_2_2945225080250994454/py_scripts/examples.py", line 5, in print_arg
 int("a1234")
 from ValueError: invalid literal for int() with base 10: 'a1234' (runtime)

In this example, we use echo> operator to show the error message, but you can use mail> operator for sending Email or http> operator to send a Slack message.

Pythonistaのためのdigdag py> operator開発ガイド

Tue, 24 Dec 2019 00:00:00 +0900

Table of Contents

この記事は、Arm Treasure Data Advent Calendar 2019の24日目です。

今年の夏に新しくTreasure Dataで使えるようになったPython Custom Scriptingですが、開発する際にどういう点を気をつければ良いのかという質問をいただくことが多いので、今日はTreasure Workflowとdigdagのpy> operatorを使った開発の際に気をつけることを書いて行こうと思います。

なお、Treasure WorkflowとありますがOSSのdigdagでも活かせる内容があると思います。

なお、既にPython Custom Scriptingが試せる環境にある方は、このGoogle Colab notebook https://bit.ly/191212_cs で一通り試すことが出来ます。

workflowをpushするまえにローカル環境で開発とテストをする方法

基本戦略:Pythonのタスクを合理的な粒度にまとめる

Treasure Workflowやdigdagのサーバーモードでは、タスク間の中間ファイルを置くためのストレージがないため、一つ一つのタスクの粒度が大きくなりがちです。特に、Treasure Workflowでは一つ一つのtaskでコンテナが起動するため、そのオーバーヘッドを無視できません。一方で、一つの巨大なタスクは、開発時のデバッグを難しくさせます。そこで、開発時の戦略としては一つ一つは最低限の塊に分けた関数を用意します。そして、必要に応じてそれらを束ねる関数を用意するのが良いでしょう。

Treasure Workflow向けのworkflowをローカル環境で開発するにはいくつかの選択肢があります。

Treasure Dataの公式Dockerイメージを使う
Dockerイメージと同じPythonの仮想環境を使う

1. Treasure Dataの公式Dockerイメージを使う

基本的にはTreasure Dataが提供している公式イメージを利用すると、本番環境と同じイメージが使うことができるので良いでしょう。

その際には、他のPythonスクリプトの開発と同様に、切り分けた単体で実行できるようにして開発するのが良いでしょう。

if __name__ == "__main__":
 your_function("default_argument")

2019/12/23現在、最新のDocker imageは以下の2つです。

digdag/digdag-python:3.7 https://hub.docker.com/r/digdag/digdag-python
digdag/digdag-anaconda3:2019.03 https://hub.docker.com/r/digdag/digdag-anaconda3

PyCharmのProfessional Editionを持っている場合、Dockerのコンテナにremote debuggerがアタッチできるので便利です。詳しくはPyCharmのドキュメントをご参照ください。

2. Dockerイメージと同様のPythonの仮想環境を作る

Python は仮想環境を作るための venv と呼ばれるモジュールがあります。これを使うことで他のプロジェクトと分離したパッケージの環境を作ることができます。

digdag-python:3.7

digdag-python:3.7と同様の環境を作るには、次のgistからrequirements.txtとconstraints.txtをダウンロードします。 https://gist.github.com/chezou/d0a0fc62007af4d808752e78b31ae694

その後、以下のようにコマンドを実行することでDockerイメージと同様のPython環境が構築できます。

$ python -m venv .venv
$ source .venv/bin/activate
(.venv)$ pip install -r requirements.txt -c constraints.txt

この方法では、OSによる差異まで吸収ができない場合があります。例えば、digdag-python:3.7はDebianベースなので、OSレベルのパッケージ管理は apt-get を使いますが、それをスクリプト内に書いても実行ができません。

digdag-anaconda3:2019.03

anacondaイメージと同じ環境を作りたい場合は、gistからenvironment.ymlをダウンロードします。 https://gist.github.com/chezou/d0a0fc62007af4d808752e78b31ae694#file-environment-yml

その後、以下のコマンドを実行するとデフォルトの環境に依存するパッケージをインストールします。

conda env update -n base -f environment.yml

なお、新しい環境を構築したい場合は、environment.ymlの中の base を my-env など好きな名前に変更した後、以下のコマンドで新規仮想環境を作成してください。

conda env create -f environment.yml

py> operatorを含んだworkflowをローカルで実行する

もし、ローカル環境でworkflow全体を実行したい場合は、 ~~digdagの v0_10ブランチを使うことで、本番環境に近いdigdag環境が用意できます~~。

2019/12/23現在は、Treasure Dataではv0_10を使っていますが、将来これは変わる恐れがあります。

2021/02/14現在、v0_11へと移行しました。今後は適宜適切なブランチを使うようにしてください。 https://github.com/treasure-data/digdag/pull/1502 https://github.com/treasure-data/digdag/pull/1504

## py> operatorにパラメータを渡す

py> operatorにパラメータを渡すには2つの方法があります。

digdagの引数を使う
環境変数を使う
digdagの変数でやりとりする

1. digdagの引数を使う

以下のような py_scripts/examples.py というスクリプトがあるとします。

def print_arg(msg):
 print(f"Message is {msg}")

msg という変数を print_arg という関数に渡す場合、以下のようなdigdagのtaskになります。

+simple_with_arg:
 py>: py_scripts.examples.print_arg
 msg: "Hello World"
 docker:
 image: "digdag/digdag-python:3.7"

もし、複数の引数をPythonの関数へ渡したい場合、digdagの引数を増やせばよいでしょう。

ここで注意してほしいのが、digdagの変数はPythonにシームレスに渡されるということです。つまり、 **kwargs などで引数を受け取る場合、意図しないdigdagの変数がPythonに渡る可能性に注意してください。

例えば、上の例では docker という変数には {"image": "digdag/digdag-python:3.7"} という辞書型の変数が代入されています。ですので、 **kwargs で受けるのではなく、明示的な引数の指定を強くおすすめします。

た、同様に意図しないdigdagの変数と py> operatorの引数の衝突が起こる場合があります。以下のようなワークフローがあったとします。

_export:
 td:
 database: my_db

+simple_with_arg2:
 py>: py_scripts.examples.print_arg_td
 msg: "Hello World"
 docker:
 image: "digdag/digdag-python:3.7"

このとき、Pythonのスクリプトは以下のような関数を持っているとします。

def print_arg_td(msg: str, td: str = None):
 print(f"'msg' is {msg} and 'td' is {td}")

simple_with_arg2 タスク実行時に print_arg_td 関数へ渡される引数 td は何になるでしょうか？通常のPythonの感覚では、デフォルト値である None が期待されます。しかし、 digdagのワークフローで td という変数がすでにexportされているため、引数 td には {"database": "my_db"} という辞書が格納されてしまいます。これにより、変数 td の型(dict)が期待されていたもの(str)との不一致が起こりうるのです。

このようなミスマッチを避けるために、digdagで予約されている変数やよく利用される変数を避けたほうが良いでしょう。特に td という変数や以下の変数は避けたほうが良いです。

td.endpoint
td.apikey
td.use_ssl
td.proxy.enabled
td.proxy.host
td.proxy.port
td.proxy.password
td.proxy.user

これらの既に利用されている変数は将来的に変更される可能性があります。

digdagの組み込み変数は次のドキュメントをご参照ください。 http://docs.digdag.io/workflow_definition.html#using-variables

また、digdagは int から str など意図しない型の変換を行う場合があります。そのため、型のチェックや明示的な変換をおすすめします。

2. 環境変数を使う

環境変数は、py> operatorに変数を渡すためのもう一つの方法です。

TDのAPI keyやAWSのsecret keyなどセキュアな情報はこの形式でやりとりすることが多いです。

例えば、以下のような simple_with_env というタスクがあったとします。

+simple_with_env:
 py>: py_scripts.examples.print_env
 _env:
 MY_ENV_VAR: "hello"
 docker:
 image: "digdag/digdag-python:3.7"

このとき、 MY_ENV_VAR は以下のようにPythonから取得できます。

import os
def print_env():
 print(f'Env var is {os.environ["MY_ENV_VAR"]}')

Treasure Workflowではセキュアな情報を扱うためにdigdagの secrets を格納するデータベースを提供しています。

Digdag Secretsの設定フロー

Projectを td workflow push でプッシュする
secretsを td workflow secrets でデータベースに格納する
secretsを {secret:my_secret} という形式でworkflowに書き、環境変数経由でPythonにわたす

環境変数での受け渡しをしないとsecretsはPythonに渡されません。例えば、以下のようなワークフローとPythonスクリプトでは正しくsecretsに格納された td.apikey という情報が渡されます。

+simple_with_env2:
 py>: py_scripts.examples.access_td
 _env:
 TD_API_KEY: ${secret:td.apikey}
 docker:
 image: "digdag/digdag-python:3.7"

import os
def access_td():
 # Able to fetch API key like "1234/XXXX"
 apikey = os.environ["TD_API_KEY"]
 # Do awesome execution

しかし、以下のようにdigdagの引数として渡した場合はsecretsが評価されません。

+simple_with_env_ng:
 py>: py_scripts.examples.access_td_ng
 apikey: ${secret:td.apikey}
 docker:
 image: "digdag/digdag-python:3.7"

def access_td_ng(apikey):
 # Always shows "${secret:td.apikey}" instead of actual API key like "1234/XXXX"
 print(apikey)

secretsに関する詳細は、digdagのドキュメントをご参照ください。

3. digdagの変数を使う

digdagのpy> operatorとして実行するPythonスクリプトでは、 import digdag とすることでdigdagモジュールを利用することが出来ます。

以下のように、 digdag.env.params と呼ばれる変数に辞書のようにアクセスすることでdigdagの変数を直接読むことが出来ます。

def read_workflow_env():
 import digdag
 print(digdag.env.params["my_msg"])

このとき、実行するworkflowは例えば以下のようなものになります。

_export:
 my_msg: "awesome message"

+simple_with_arg2:
 py>: py_scripts.examples.read_workflow_env
 docker:
 image: "digdag/digdag-python:3.7"

なお、読み込みだけではなくdigdag.env.storeを使うことでdigdagの変数の書き込みもできます。ただし、あまり大きな変数の受け渡しはしないほうが良いでしょう。

def store_workflow_env(msg):
 import digdag
 digdag.env.store({"my_msg": msg})

このdigdagモジュールは、digdagがpy> operator実行時に動的に生成しているため、ローカルでは実行できないことに注意してください。ローカルの実行を考慮する場合は、 try-expect を利用するのが良いでしょう。

try:
 import digdag
 digdag.env.store({"feature_query": feature_query})
except ImportError:
 pass

PythonやOSのパッケージのインストール方法

Treasure WorkflowではDocker imageに入っていないパッケージは os.system や subprocess.runを使い実行します。

import os, sys
os.system(f"{sys.executable} -m pip install --upgrade pytd==1.4.3")

import subprocess
# arguments should be passed by list
subprocess.run([sys.executable, "-m", "pip", "install", "--upgrade", "pytd==1.4.3"])

この際、パッケージのバージョンを指定しましょう。

OSのパッケージのインストールの場合も同様です。

import os
os.system("apt-get update") # Need to run before doing apt-get install
os.system("apt-get install -y wkhtmltopdf")

py> operatorを含むディレクトリ構成

一つのプロジェクトでは、以下のようなディレクトリ構成をおすすめしています。

my_project
├── README.md
├── config
│ ├── params.test.yml <- Configuration file for run through test. Mirror params.yml except for `td.database`
│ └── params.yml <- Configuration file for production
├── awesome_workflow.dig <- Main workflow to be executed
├── ingest.dig <- Data ingestion workflow
├── py_scripts <- Python scripts directory
│ ├── __init__.py
│ ├── data.py <- Script to upload data to Arm Treasure Data
│ └── my_script.py <- Main script to execute e.g. Data enrichment, ML training
├── queries <- SQL directory
│ └── example.sql
├── run_test.sh <- Test shell script for local run through test
└── test.dig <- Test workflow for local run through test

この構成に従ったdigdagプロジェクトをcookiecutter-digdagを使うことで簡単にテンプレートから生成できます。 https://github.com/chezou/cookiecutter-digdag

実行時のエラーを通知する

Pythonのスクリプト実行時に発生したエラーをSlackなどで通知したい事があると思います。 digdagは _error: でworkflowが失敗した際の処理をできますが、そのとき${error.message}の中にPythonの例外情報が入っています。

以下のようなworkflowとPython scriptがあったとします。

+simple_raise_error:
 py>: py_scripts.examples.error_sample
 docker:
 image: "digdag/digdag-python:3.7"

_error:
 echo>: ${error.message}

def error_sample():
 int("a1234") # raises ValueError

このとき、以下のようなログが得られます。

2019-12-24 23:06:32 +0900 [INFO] (0039@[0:python]+simple^error): echo>: Python command failed with code 1: invalid literal for int() with base 10: 'a1234' (ValueError)
 from Traceback (most recent call last):
 from File ".digdag/tmp/digdag-py-2-1815457087076518360/runner.py", line 165, in <module>
 result = callable_type(**args)
 from File "/private/var/folders/y9/bnjb3krn39s22rmg_wvlnf7m0000gp/T/digdag-tempdir2111531196420040503/workspace/1_simple_1_2_2945225080250994454/py_scripts/examples.py", line 5, in print_arg
 int("a1234")
 from ValueError: invalid literal for int() with base 10: 'a1234' (runtime)

この例では、echo> operatorでエラーを出力しているだけですが、Slack等に例外を送ることで定期実行しているPythonタスクの通知が簡単に行なえます。

まとめ

このように、様々なポイントをおさえることでTreasure Workflowの開発をしやすくなるかと思います。また、digdagでもいくらかのポイントは使うことができるかと思います。

How to release Python package from GitHub Actions

Tue, 26 Nov 2019 01:42:11 +0900

Photo by on

Recently, I changed my CI from Travis to GitHub Actions. GitHub Actions is handy and useful for testing, publishing Python packages.

Testing Python code on GitHub Actions

Migration from Travis is super easy, just writing a simple workflow like:

The benefits of GitHub Actions for Python are:

We can use build matrix (e.g., OS and Python versions) like Travis
Launch time of GitHub is faster than Travis
Easy for additional dependency installation by using uses syntax, which uses another workflow

For example, installing JDK can be written as:

- uses: actions/setup-java@v1
 with:
 java-version: '12'
 java-package: jdk
 architecture: x64

The downside of GitHub Actions are:

Unable to
Hard to find the resources for debugging on the internet and unable to ssh to the instance

Releasing Python package from GitHub Actions to PyPI

I created the workflow like the following sequence:

Push a tag from local, or create a tag on GitHub. Using enables you to make a new version from Git tag
GitHub Actions creates GitHub release from the tag
GitHub Actions publishes wheel to PyPI by using PyPI API Token

You can see the actual workflow on GitHub:

The key points are:

Triggering the workflow from Git tag

on:
 push:
 tags:
 - 'v\*'

2. Adding dependency for deploy task

deploy:
 needs: release

needs syntax supports to write dependency. In this case, I describe release job for creating GitHub release, and then deploy job publishes the package to PyPI.

3. Preparation secrets for PyPI

Recently, PyPI provides API tokens for package publishments so that you can get an API token for the specific project. See details on the official document since it is under beta, and spec might change.

After getting API Token from PyPI, you can set secrets on GitHub by clicking “Settings” -> “Secrets” on the project page. Using my example workflow, you should set __token__ for PYPI_USERS , and a token starting with pypi- got on PyPI configuration for PYPI_PASSWORD .

Now, you can publish Python package to PyPI by just tagging on GitHub.

Use Markdown document on brand new PyPI

Tue, 17 Apr 2018 13:21:33 +0900

Yesterday, PyPI was renewed to the next-generation site. It is modern and stylish one.

@aodag told me that PEP 566, which was accepted Feb. 2018, allows us for a document on PyPI to use not only reStructuredText but also other formats such as Markdown.

So I enabled my Markdown document on brand-new PyPI.

Upgrade Python packages (if necessary)

We can use Markdown with setuptools as of v.38.6.0. Let’s upgrade you python packages if needed. Without that, Markdown description will not be rendered appropriately.

$ python -m pip install --upgrade pip $ pip install –upgrade wheel
$ pip --version pip 10.0.0 from c:\\users\\chezo\\documents\\source\\tabula-py\\venv\\lib\\site-packages\\pip (python 3.6) $ pip list
Package Version Location
-—————- ———– ————————————–
(…snip…)
setuptools 38.1.0
(…snip…)
wheel 0.31.0

Modify setup.py

If you’ve already used README.md as a long description on PyPI, all you have to do is to add long_description_content_type to setup.py as follows:

long_description=open('README.md').read(),
long_description_content_type="text/markdown",

You can see the full description of the PR :

Handle markdown long description for Pypi by chezou · Pull Request #85 · chezou/tabula-py
_Thanks for PEP 566, as of setuptools v38.6.0, PyPI can render long description written in markdown. This PR allows…_github.com

Build a wheel and upload with twine

Now, you can build a wheel and upload with twine.

$ python setup.py bdist_wheel
$ twine upload dist/*

The Markdown document was rendered!

CAVEAT: I didn’t upgrade PyPI because it is too much to bump up for just rendering Markdown. I tested on test.pypi.org.

References

新しいPyPIでMarkdownのドキュメントを使う

Tue, 17 Apr 2018 12:55:15 +0900

長い間、Pythonでパッケージを作った場合、構造化されたドキュメントを使う場合は、reStructuredText (reST)でドキュメントを書く必要がありました。

ところが、aodag さんに教えてもらったのですが2018年2月にアクセプトされたPEP 566のおかげで、PyPIのドキュメントがtxtかreSTでなければいけないという制約が外れました。そこで、昨日新しくなったばかりのPyPIでMarkdownがレンダーできる方法を試してみました。

(必要に応じて)ライブラリをupgradeする

Markdownが扱えるようになったのは、setuptoolsのv38.6.0からです。古いバージョンだとMarkdownがレンダーされないので、合わせてpipとwheelをupgradeしておきました。

setup.pyを編集する

long_description_content_typeという項目をsetup.pyに追加することで、reST以外の形式を使えるようになります。Markdownであれば例えば以下のようになると思います。

long_description=open(‘README.md’).read(),
long_description_content_type=”text/markdown”,

元々README.mdを読むようにしていたので、今回は long_description_content_type の行を追加するだけで済みました。

実際のPRはこちらです。

wheelを作ってtwineでアップロードする

後はいつもどおりwheelを作ってtwineでPyPIにアップロードしました。なお、

$ python setup.py bdist\_wheel $ twine upload dist/*

test.pypi.orgのMarkdownのドキュメントの様子

今回はこれだけのためにpatch versionを上げるのもなぁということで、test.pypi.orgにあげています。

参考文献

PEP 566の関連箇所
https://github.com/pypa/readme_renderer
https://github.com/pypa/sampleproject/pull/66

Python basics: package management

Wed, 30 Aug 2017 11:31:15 +0900

Python is a very famous programming language for machine learning. In this article, I will introduce basic Python environment.

Glossary

I will introduce basic terms about Python package management.

pip: A tool for package installation. It retrieves Python packages from PyPI. pip is gem command of Ruby.
virtualenv: Package isolation tool for Python. It has similar function with bundler of Ruby, but it also has the function to change Python versions over 2.x and 3.x.
venv: It is an official tool for package isolation introduced from Python 3.3. But, if you want to use Python 2.x or you are Debian/Ubuntu user, I recommend you to use virtualenv.

venv switches with a command like python3.5 -m venv some-awesome-env, so it can’t handle over Python 2 and 3. venv installed by Debian/Ubuntu installs useless dependencies for other OSs, so I’m an Ubuntu user so I don’t use venv.

These are common tool sets for many Pythonistas. They are recommended tools of PyPA, a working group that maintains many of the relevant projects in Python packaging.

There is one more tool that is for the specific purpose.

conda: conda is a tool for package management for scientific computation developed by Anaconda, Inc. It can manage not only Python but also R. PyData community loves conda.

I use conda for my work, but I recommend you to know the pros/cons of conda and virtualenv/venv and chose write tool for your purpose.

Installation of Python

Since it is 2017, Python beginners should use the latest version of Python 3. However, there are some cases to use Python 2.x for some painful reasons.

If you need to install Python 2 and 3, you can install multiple Python with package management tools like apt or yum. In Ubuntu, you can install Python 2.7 with apt install python-dev, and you can install Python 3.6 via apt install python3-dev.

After installation, you can see the Pythons under /usr/bin:

/usr/bin/python #<- 2.7
/python2 #<- 2.7
/python2.7 #<- 2.7
/python3 #<- 3.6
/python3.6 #<- 3.6

If you’re macOS user, you can install both Python 2 and 3 via brew install or port install.

For Windows users, you can install Python 2 and 3 using official installer or Chocolatey. From Python 3.6 for Windows, there is py command that switches Python version.

Caution: Never try to keep using System Python. System Python is often old, and it depends on system critical system such as yum. If you run sudo pip install carelessly, there is a risk of destroying the environment of the OS itself.

Package management

As I mentioned, you should not do sudo pip install awesome-package. Hence, Many important systems depend on system Python, don’t use sudo pip.

If you’re a venv user, this tutorial will help you.
https://docs.python.jp/3/tutorial/venv.html

For virtualenv users, I will write a tutorial of virtualenv. It is a translation of the document written by aodag.
https://gist.github.com/aodag/bea141d255e22d204a2140fba658ebf2

Why should we use virtualenv/venv?

virtualenv avoids:
- Conflicting Python packages with system Python
- Conflicting packages between projects
- Losing sight of which project depends on those packages

Install virtualenv

First, you can install virtualenv under user home directory.

$ wget https://bootstrap.pypa.io/get-pip.py
$ export PATH=”~/.local/bin/:$PATH”
$ python get-pip.py --user
$ pip install virtualenv --user
\# Windows user can isntall just via \`pip install\`
\> pip install virtualenv

With --user option, you can install packages under user directory.

virtualenv can create a Python virtual environment. Creating the environment under the project root is common.

Run virtualenv as follows:

$ virtualenv venv -p python3.6

then, you can get virtual environment.

Since Python packages will be installed under the venv directory, don’t forget to add venv directory into .gitignore.

$ source venv/bin/activate
(venv) $
\# For Windows
\> . venv/Script/activate

Install Python packages via pip

You can install packages via pip. After activating virtualenv/venv, pip will install packages under venv directory.

(venv) $ pip install pyramid

If you want to install the specific version of the package, you can set version number:

(venv) $ pip install pyramid==1.8.1

Without version number, pip will install latest stable version.
https://www.python.org/dev/peps/pep-0440/

You can list installed packages with pip list command.

(venv) $ pip list
numpy (1.13.1)
pandas (0.20.3)
pip (9.0.1)
pkginfo (1.4.1)
pytest (3.2.0)
python-dateutil (2.6.1)
pytz (2017.2)
wheel (0.29.0)

Managing package version

From pip 7.1, we can fix version of packages with constraints.txt. Using pip freeze command, you can list packages with a version number.

(venv)$ pip freeze -l
numpy==1.13.1
pandas==0.20.3
pkginfo==1.4.1
pytest==3.2.0
python-dateutil==2.6.1
pytz==2017.2
(venv)$ pip freeze -l > constraints.txt

You should list your required packages into requirements.txt,

(venv)$ cat requirements.txt
pandas
numpy

Then you can install required packages as follows:

(venv)$ pip install -r requirements.txt -c constraints.txt

Levelaging wheelhouse

Modern Python package is distributed by wheel format, which is the binary type format. There is another format, sdist, which is the source type format and it requires compile from source if it depends on native codes. I highly recommend using wheel format, because it is faster installation than sdist without compilation and even if you have an offline environment which unable to connect PyPI you can deploy the project easily.

Put all dependent .whl format package files under wheelhouse directory, you can install as follows:

$ pip install -r requirements.txt -c constraints.txt -f wheelhouse — no-index

-w or --wheel-dir option allows you to set wheel directory. -f or--find-links option uses wheelhouse directory primary.--no-index option prevent to connect PyPI.

If you want to export all the dependencies into wheelhouse directory, you can use pip wheel command.

$ pip wheel -r requirements.txt -c constraints.txt -w wheelhouse

Should I use conda?

Anaconda is a Python distribution for scientific computing such as machine learning. Anaconda suit consists of Anaconda, which includes the recommended package and Miniconda, which is the minimum environment for conda and you can install only necessary packages yourself. Anaconda sometimes includes heavy packages. It used to include Django, so check the default package and use it properly.

Unlike virtualenv, Anaconda can create its original virtual environment. Characteristically, using the --copy option makes it possible to copy system level libraries, .so, etc. without creating symbolic links. If you archive a set of virtual environments with zip or tar, you can use it on other machines.

$ conda create -n myenv --copy python=3.6
$ conda activate myenv

In other words, libraries, which are managed by OS level package management tools such as apt, are also managed by conda. Conda has its own package repository different from PyPI and upload binaries for each OS on it. Since the same package, such as OpenCV, is registered in the repository by multiple users, you should care which package is the best one.

In many machine learning books, it is often written that conda can be used, but I think that it is better not to use it much outside Windows.

The reasons are as follows:

In 2017, wheel is de facto for the binary package format, so conda’s original purpose, handling scientific packages like numpy, or Scipy, can be done without conda.
conda will replace commands such as openssl/curl/python in macOS / Linux System (strictly speaking, conda will pass PATH first) \[[issue](https://github.com/ContinuumIO/anaconda-issues/issues/1119)\]
Package developers are often not conda users, and they seem to be asked for support in an environment that they do not normally use, such as JRuby or Rubyinius (or Windows specific trouble).
In the conda world, it is difficult to pass information that should be included in a build of a native extension (such as Cython dependence)

So I recommend using conda for Windows users or people do not develop heavily but want to experience machine learning. Or, put Miniconda under pyenv control. I use conda under Docker environment.

However, we can not install the package like Scipy on Windows via pip install, you need to download wheel on your own. I think that this point is better for honest conda.

Historical details are detailed in this article. In short, because old binary format egg was not good, conda was created.

Conclusion

I introduced installation of Python and how to manage Python packages. I think we can manage Python packages via virtualenv/venv well without conda, but there is good case for conda to pack some environment with system libraries.

References

Original Japanese document:

Pythonの環境構築を自分なりに整理してみる

Sat, 26 Aug 2017 13:58:07 +0900

先日、 kawasaki.rb の懇親会で「AWS LambdaのためにPythonはじめたいんです」とか「機械学習系の本を読み始めたので、そこに書いてあったcondaではじめました」とかいう話を聞きました。

コレ読んでおけ系の記事は既に色々とあるんですが、今回は自分で触ってきて使っている環境を中心に説明をしようと思います。想定読者としては、Rubyを使っていたけど最近Pythonにも手を出すようになってきたという人です。

書き始めてから思ったんですが、ぶっちゃけPythonコミッターのmethaneさんの以下の記事を読めば十分な気もしてきましたが、一例としてお読みいただければと思います。

私の立ち位置

もともとは、数年前まで年に一回Python3でNLTKやらscikit-learnやら機械学習や自然言語処理の環境を作ろうと試みては失敗してPython使うものかと思っていた人でした。それが、Anacondaで環境導入すると、面倒なことは何も考えずに済むということを知り、CookpadではAnacondaを前提に環境構築を勧めていました。

今は、ymotongpooに「郷に入っては郷に従え」と言われたため、pip+virtualenv/venvで全てをこなしていますが、これで困ったことは特にありません。macOS, Windows, Linuxそれぞれでやっていますが、大きな苦労もなく大丈夫だなという印象です。

先に言っておくと自分のPython力はそこまで高くないです。もともとはRailsで開発はしていましたが、Pythonはほぼ機械学習やデータマイニング系のコードを一人で書くということが多いです。いくつかPythonのライブラリは書いて入るのですが、チーム開発の経験はないためその観点は弱いということを認識いただければと思います。

なお、仕事ではので、適材適所だなと思ってこの話を書いています。単純にpyenvやcondaを使うな、というつもりはありません。リスクとベネフィットのトレードオフで選んでください。

環境構築のあれやこれや

以下では、macOS, Windows, Linuxで自分がどのように環境構築をしているかについて書いていこうと思います。

最低限の前提知識

Pythonの実行環境の導入・パッケージ管理周りに出て来るキーワードについて簡単に説明します。

pip: パッケージインストールのためのツール。Rubyでいうところのgem。パッケージはPyPIというRubyで言うところのrubygems.orgから取ってくる。
virtualenv: パッケージを切り分ける仮想環境を作る人。Rubyで言うところのbundlerに近いが、Pythonの利用するバージョンも指定するのでrbenvのruby-build抜きの機能を持っている感じ
venv: Python 3から公式として入ったvirtualenv。ただし、venvはPythonのバージョン指定ができないとか、Debian/Ubuntuでは余計な依存関係が発生するとかで私は使ってません。

\[2017/08/30 追記\]

venvはバージョンの指定が出来ないのではなく、2.7と3.6との切り替えができないという意味でした。 python3.5 -m venv some-great-envで切り分けられます。
私自身パッケージ開発に2.7サポートをする場合があるのと、Ubuntu使いなのでvirtualenvを使っています。

\[/追記\]

以上が、多くのPythonistaに使われている基本的なツールセットです。このあたりの話は、PyPAと呼ばれるパッケージ管理関係の標準と参照実装を決める目的で設立された団体によってとして扱われています。（後述のcondaもでてきますが）

conda: Continuumという会社が作っているPythonを中心とした科学計算のパッケージ管理をするためのプラットフォーム
pyenv: rbenvのPython版。Pythonのソースからのビルドと、Pythonの実行環境（バージョンなど）の切り替えをする

これらは、特定の目的のために使うことが多いものです。

実行環境の導入

2017年においては、Python 3系の最新版を入れておけばだいたい生きていけると思います。が、何かしらの辛い事情で2系も使わないといけない場合もあるかと思います。

その場合は、自分はOSのパッケージ管理ツールでPythonを入れています。例えばUbuntuで apt install python-dev とするとPython 2.7が apt install python3-dev をすると今ならPython 3.6が入ります。同時に入れると

/usr/bin/python #<- 2.7
 python2 #<- 2.7
 python2.7 #<- 2.7
 python3 #<- 3.6
 python3.6 #<- 3.6

という感じで入ります。 brew installでも python と python3 で2系と3系両方入れることができます。

バージョンの切り替えは、後述のvirtualenvで実行するバージョンを切り替えます。逆に言うとpyenvでのバージョン切り替えは、ライブラリ開発者のように細かいバージョン切り替えが必要な人でなければ不要でしょう。

なお、homebrewは彼らの方針で過去バージョンのPythonはpyenvを使ってくれ、と言っています。MacPortsは普通に過去バージョンが入りますし、Ubuntuはを使えばこの問題は解決される話です。homebrewで切り替えたい人はpyenvを使うほうが楽でしょう。

WindowsだとChocolateyで入れるか、オフィシャルのインストーラで入れれば良いです。（ Python 3.6からは py というコマンドが用意されており、それを使うとバージョンを切り替えた実行もできます）

なお、絶対にやってはいけないのはSystem Pythonを使い続けることです。System Pythonは往々にして古いことが多く、またyumなどシステム上重要なシステムに依存しています。うっかり、 sudo pip install などしようものなら、環境を壊してしまう恐れがあります。

なお、環境構築に関する話は、以下の記事が参考になるでしょう。

パッケージ管理

まず、大前提として先程も書きましたが sudo pip install hogehoge をするのは辞めましょう。システムPythonはOSで使っているため、これの環境を壊すことは危険です。

プロジェクトごとにパッケージのバージョンを依存関係を切り替えるのには virtualenvを使います。以下の aodagさんの資料を読んで下さると良いと思います。

また、Python 3に関しては以下の venvのチュートリアルがわかりやすくまとまっています。Debian/Ubuntu以外の人はPython 3だけで良ければ venv で十分かと思います。

ここに書いてあるけど大事な話としては、 virtualenvでPythonの実行環境を切り替えられる話をしておきます。

まずは、以下のようにしてユーザ領域に virtualenvを入れます。

$ wget https://bootstrap.pypa.io/get-pip.py
$ export PATH="~/.local/bin/:$PATH"
$ python get-pip.py --user
$ pip install virtualenv --user

# Windowsの場合は特に考えずにpip installで良い
> pip install virtualenv

virtualenvでは、プロジェクトの下に仮想環境を作ります。プロジェクトルートで以下のコマンドを実行すると

$ virtualenv venv -p python3.6

Python 3.6を実行環境とした、仮想環境ができます。

$ echo venv >> .gitignore

で、 .gitignore に追加しておくとよいでしょう。

次に、 activate して仮想環境を有効化します。

$ source venv/bin/activate(venv) $

#Windows
> . venv/Script/activate

この状態で、 pip install scikit-learn とすると venv 以下にパッケージが入ります。仮想環境の利用を止めたい場合は deactivate コマンドを使いましょう。

pip 7.1以降ではconstraints.txtというGemfile.lockのようなものが扱えるようになりました。 pip freeze で現在インストールしているライブラリとバージョン一覧がでます。

(venv)$ pip freeze -l
pylint==1.7.2
pyparsing==2.2.0
pytest==3.2.1
requests==2.18.4
six==1.10.0
tox==2.7.0
urllib3==1.22
virtualenv==15.1.0

(venv)$ pip freeze -l> constraints.txt
(venv)$ cat constraints.txt
pylint==1.7.2
pyparsing==2.2.0
pytest==3.2.1
requests==2.18.4
six==1.10.0
tox==2.7.0
urllib3==1.22
virtualenv==15.1.0

ここに、プロジェクトに必要な必要なライブラリをrequirements.txtに記述します。

(venv)$ cat requirements.txt
requests
pyparsing

そうすると、以下のコマンドで必要なライブラリの必要なバージョンを入れることができます。

(venv)$ pip install -r requirements.txt -c constraints.txt

condaの話

Anacondaは機械学習などの科学計算向けのPythonディストリビューションです。Anacondaは、推奨パッケージを含めて入れるAnacondaと、自分で必要なパッケージを入れるMinicondaが入ります。Anacondaは（今はないですが）昔はDjangoを入れているなど重いパッケージも入ってくることがあるので、きちんとデフォルトパッケージを調べてから使いましょう。

なお、Pythonディストリビューションと書いてありますが、Rなど他の言語の環境を作ることもできます。

Anacondaはvirtualenvと違い、独自の仮想環境を作ることができます。特徴的なのは、 --copy というオプションを付けるとライブラリや.soなどをシンボリックリンクを作らず、コピーするということができるため、仮想環境一式をzipやtarで固めると、そのまま実行可能な形で使いまわせることです。

$ conda create -n myenv --copy python**\=**3.6
$ conda activate myenv

つまり、通常 apt などのOSのパッケージ管理で入れるようなところも、condaのパッケージで管理をします。condaはPyPIとは異なる独自のパッケージリポジトリを持ち、そちらにOSごとにバイナリをアップロードします。ですので、OpenCVなど同じ名前の同じものを入れるためのパッケージが複数のユーザによってレポジトリに登録されていたりと結構雑多な印象があります。

多くの機械学習の本では、condaを使えと書いて有ることが多いのですが、Windows以外ではあまり使わないほうが良いと私は考えています。

理由としては、以下が上げられます。

2017年においては、 wheel というバイナリパッケージのフォーマットがデファクトになっているので、condaの当初の目的の科学計算用のパッケージ（gfortanとかに依存していて辛い）を簡単に入れるという目的はcondaでなくてもできる。
普通に入れると、macOS/Linuxの (厳密には、 condaの方が先にPATHが通ってしまう) \[[issue](https://github.com/ContinuumIO/anaconda-issues/issues/1119)\]
パッケージ開発者は、condaユーザーではないことが多く、彼らからするとJRubyやRubyinius（あるいはWindows固有の不具合）など通常使わない環境でのサポートを求められるように感じる。
condaの世界で閉じていないNative extensionのビルド（Cython依存など）でincludeしないといけない情報などがうまく渡せず、はまると辛い
Distributionごとの違いが発生する場合もあるのに、OSレベルの違いしか考慮できない

ですので、Windowsの人や、開発は通常しないけど機械学習を体験してみたいという人はcondaを使うと良いでしょう。あるいは、pyenvの管理下でMinicondaを入れるか、私自身はDockerの中でcondaを使っています。

ただ、ScipyなどWindows用の一部は pip installでは入らないので wheelをダウンロードする必要があります。この点は正直condaの方が良いかと思います。

歴史的な詳細は下記が詳しいです。端的に言うと、wheel以前の古いバイナリフォーマットがいまいちだったため、condaを作ったという形になります。

カルチャーの違い

RubyとPythonでは色々と文化が違うのですが、一番大きな違いは個人的には以下の2点だと思っています。

できるだけ依存するものは最低限の薄いものが良い。ブラックボックスは好まないという思想
Rubyはいいものを皆が試して事実上のデファクトスタンダードになるのに対して、提案されたPEPという「標準」を合議して決めていくというスタイル

なので、Rubyはパッとデファクトが決まる印象がありますが、Pythonはじっくり議論の上で標準を決めていくという印象があります。（コレもあって、過渡期の実装が色々出てくる）

また、こうした経緯からかPythonの人たちはきっちり例外まで補足したがる傾向にあると思います（例えるなら、Pythonは数学科の数式にきっちり向き合う感じと、Rubyは工学部の数式に対する雑な扱いのような感じ）。なので、昔からのPythonistaが書くドキュメントは長くなる傾向にあると思いますが、そういうものだと思って割り切るしかないと思います。

まとめ

個人的には、普通に使う分にはvirtualenv/venvとOSのパッケージ管理ツールでPythonを入れるというので、私は良いと思って使っています。

ただ、プロダクション要求などで必要なものもあると思うので、condaとpyenvは適材適所で用法用量を守って使いましょう。

参考文献

Simple way to distribute your private Python packages within your organization

Mon, 24 Jul 2017 01:21:40 +0900

[https://www.irasutoya.com/2017/05/blog-post\_22.html](https://www.irasutoya.com/2017/05/blog-post_22.html)

https://www.irasutoya.com/2017/05/blog-post_22.html

This article is a translation of this article, originally written by aodag in Japanese. I translated it with his permission. This article is aimed to know simple ways to prepare internal Python package host like a local gem server on Ruby.

Methods

Include your packages in your git repository
Publish a directory including your packages via HTTP server
Build a local PyPI-equivalent server

It is a high-cost way to create a local PyPI-equivalent server (translator note: like devpi), and I don’t think there is no need to do so, I will describe first two options.

Include your packages in your Git repository

If your packages are required for a particular project, it is straightforward to contain them in the Git repository. You can put them in the directory named wheelhouse, which comes from the name of the previous default directory created by pip wheel. (translator note: this method is assumed you to know wheel. If not, this story and this JIRA would be helpful.)If you put the private package foo in the wheelhouse, you can install as follows:

$ pip install foo -f wheelhouse

Note that -f is the short option for --find-links, with that option, pip will search packages in the directory first, then fall back to pypi.

Publish a directory including your packages via HTTP server

We can use--find-link option to search not only local directory but also a remote server via http. If you have a package used by multiple projects, this method will help you.

The easiest way to distribute your packages with this method is executing python -m http.server with Python 3.x (or python -m SimpleHTTPServer with Python 2.7) on the wheelhouse directory. This simple server provides directory listings so that we can just use--find-links to use the directory. Make sure to open http://localhost:8000 that you can see the list of files under the wheelhouse directory via a web browser.

To install foo package via HTTP server you launched, you can execute as follows:

$ pip install foo -f http://localhost:8000

Since this is a simple server, for production, it is good to put them in cloud storage such as AWS S3, you should check the way for directory listings, or you can use Apache with DirectoryIndex enabled.

Conclusion

I recommend these methods because they are simple and no need to prepare the dedicated application server.

Python | Democratizing Data

Scrape Notion and convert into PDF

Recipe on Notion is good, if it’s printable

Scrape Notion with Python

tabula-py 2.8.0 now uses jpype to launch JVM

How fast is it?

Caveats

Challenges for releasing v2.8.0

The test issue with different java_options

Read the docs default behavior change

4 Steps to Release a CLI in Python

Create a project by using poetry

Create a CLI with Click/Cloup

Use poetry-dynamic-versioning for version management

Introduce GitHub Actions to release the package to PyPI

py> operator development guide for Python users

How to build & test custom scripts on local env before pushing

1. Use TD docker image

2. Create a Python virtual environment on local env

Test a workflow including Python

Passing Parameters to py> operator

1. digdag argument

2. environment variable

3. digdag variable

Directory structures

How to install Python packages / OS packages

How to read/write tiny variables between digdag tasks

Error notification with Python stack trace

Pythonistaのためのdigdag py> operator開発ガイド

workflowをpushするまえにローカル環境で開発とテストをする方法

基本戦略:Pythonのタスクを合理的な粒度にまとめる

1. Treasure Dataの公式Dockerイメージを使う

2. Dockerイメージと同様のPythonの仮想環境を作る

digdag-python:3.7

digdag-anaconda3:2019.03

py> operatorを含んだworkflowをローカルで実行する

1. digdagの引数を使う

2. 環境変数を使う

Digdag Secretsの設定フロー

3. digdagの変数を使う

PythonやOSのパッケージのインストール方法

py> operatorを含むディレクトリ構成

実行時のエラーを通知する

まとめ

How to release Python package from GitHub Actions

Testing Python code on GitHub Actions

Releasing Python package from GitHub Actions to PyPI

Use Markdown document on brand new PyPI

Upgrade Python packages (if necessary)

Modify setup.py

Build a wheel and upload with twine

The Markdown document was rendered!

References

新しいPyPIでMarkdownのドキュメントを使う

(必要に応じて)ライブラリをupgradeする

setup.pyを編集する

wheelを作ってtwineでアップロードする

test.pypi.orgのMarkdownのドキュメントの様子

参考文献

Python basics: package management

Glossary

Installation of Python

Package management

Why should we use virtualenv/venv?

Install virtualenv

Install Python packages via pip

Managing package version

Levelaging wheelhouse

Should I use conda?

Conclusion

References

Pythonの環境構築を自分なりに整理してみる

私の立ち位置

環境構築のあれやこれや

最低限の前提知識

実行環境の導入

パッケージ管理

condaの話

カルチャーの違い

まとめ

The test issue with different `java_options`