img2url 0.2.0

# img2url

## Introduction

img2url transforms a local image file to an url by uploading the file to remote. img2url helps you write portable document, especially markdown file, in such a way you don't need to worry about where to place the static resource like images!

Supported remotes:

* GitHub Repository (by default).
* Qiqiu Object Storage.

## Install

img2url is a Python project, use `pip` to install:

```
pip install img2url
```

## Command-Line Interface

And the CLI is pretty simple:

```
$ img2url --help
Usage:
img2url [--no-clipboard] <path>
img2url [--no-clipboard] (-m | --markdown) <path>

Options:
--no-clipboard Prevent copying result to clipboard.
-m, --markdown Return Markdown format of image url.
```

Example:

```
$ ls -al
total 56
drwxr-xr-x 4 haoxun staff 136 Aug 13 21:26 .
drwxr-xr-x 8 haoxun staff 272 Aug 13 21:23 ..
-rw-r--r--@ 1 haoxun staff 23975 Aug 13 21:26 image1.png
-rw-r--r--@ 1 haoxun staff 3727 Aug 13 21:26 image2.png

$ img2url image1.png
https://cdn.rawgit.com/huntzhan/img2url-repo/master/image1.png

$ img2url --markdown image2.png
```

## Configuration

User should configure img2url before actually using it, so that img2url knows where to upload the files.

Path of configuration file:

* `~/.img2url.yml`, by default.
* `IMG2URL_CONFIG_PATH`, customized path.

Currently, img2url supports following remotes, remote is specified by setting `remote` key in configuration file. If `remote` is not defined, `github` is selected as remote by default.

| Remote | Field Setting |
| -------------------- | ---------------- |
| GitHub Repository | `remote: github` |
| Qiqiu Object Storage | `remote: qiniu` |

### Configuration of GitHub Repository

Example of `.img2url.yml`:

```yaml
remote: github

githu_token: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
githu_user: img2url-testing
githu_repo: img2url-testing-travisci

proxies:
https: socks5://127.0.0.1:1080
```

Supported fields:

| field | required | default |
| ------------------------- | -------- | ---------------------------------------- |
| `github_token` | yes | - |
| `github_user` | yes | - |
| `github_repo` | yes | - |
| `github_branch` | no | `"master"` |
| `github_path` | no | `""` |
| `github_commiter_name` | no | `"huntzhan"` |
| `github_commiter_email` | no | `"programmer.zhx@gmail.com"` |
| `message_template_create` | no | `"{filename} created by img2url at {time}."` |
| `message_template_update` | no | `"{filename} updated by img2url at {time}."` |
| `proxies` | no | `None` |

Meaning of fields:

* `github_token`: [Personal access tokens](https://github.com/settings/tokens) of your GitHub account. If you don't have one, click "Generate new token" and **select the "repo" scope**, then record the generated token.
* `github_user`: Account of GitHub.
* `github_repo`: The repository to store images.


* `github_branch`: If not defined, use `master` as the default branch.
* `github_path`: Path to store the uploaded files in your repository. If not defined, use the root of repository by default.
* `proxies`: If defined, use proxy to make API requests instead of connecting directly.
* `message_template_create`: Message template for creating new file, supported variables: `{filename}`, `sha`, `time`.
* `message_template_update`: Message template for updating existed file, supported variables: `{filename}`, `sha`, `time`.
* `github_commiter_name`: Username for commit message.
* `github_commiter_email`: Email for commit message.

### Configuration of Qiqiu Object Storage

Example of `.img2url.yml`:

```yaml
remote: qiniu

qiniu_access_key: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
qiniu_secret_key: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
qiniu_bucket: img2url
qiniu_base_url: xxxxxxxxx.bkt.clouddn.com
```

Supported fields:

| field | required | default |
| ------------------- | -------- | ------- |
| ` qiniu_access_key` | yes | - |
| ` qiniu_secret_key` | yes | - |
| ` qiniu_bucket` | yes | - |
| ` qiniu_base_url` | yes | - |

Meaning of fields:

* `qiniu_access_key`, `qiniu_secret_key`: [Access/Secret Key](https://portal.qiniu.com/user/key)
* `qiniu_bucket`: the name of Qiniu object storage space.
* `qiniu_base_url`: domain of Qiniu object storage space.