Skip to content

Commit

Permalink
Improve argparser (#87)
Browse files Browse the repository at this point in the history 
Co-authored-by: cdce8p <30130371+cdce8p@users.noreply.github.com>

Squashed commit of the following:

commit b7949b5
Author: cdce8p <30130371+cdce8p@users.noreply.github.com>
Date:   Fri Jan 22 14:04:52 2021 +0100

    Small bugfixes

commit 8441671
Author: cdce8p <30130371+cdce8p@users.noreply.github.com>
Date:   Tue Jan 19 20:44:22 2021 +0100

    Update gitignore

commit 53ebae0
Author: cdce8p <30130371+cdce8p@users.noreply.github.com>
Date:   Tue Jan 19 20:00:13 2021 +0100

    Add type hints for args

commit ebc95e2
Author: cdce8p <30130371+cdce8p@users.noreply.github.com>
Date:   Tue Jan 19 19:52:04 2021 +0100

    Add isort config + reorder imports

commit 3f08e86
Author: cdce8p <30130371+cdce8p@users.noreply.github.com>
Date:   Tue Jan 19 19:50:15 2021 +0100

    Add arg verify

commit 2b885a1
Author: cdce8p <30130371+cdce8p@users.noreply.github.com>
Date:   Tue Jan 19 00:39:06 2021 +0100

    Bugfix display default values

commit 72ddf16
Author: cdce8p <30130371+cdce8p@users.noreply.github.com>
Date:   Mon Jan 18 23:54:10 2021 +0100

    Use enums for arguments (from, order, format)

commit 99ec862
Author: cdce8p <30130371+cdce8p@users.noreply.github.com>
Date:   Mon Jan 18 17:09:50 2021 +0100

    Update readme

commit 44cdf4e
Author: cdce8p <30130371+cdce8p@users.noreply.github.com>
Date:   Mon Jan 18 16:48:56 2021 +0100

    Add custom help text formatter

commit 52055be
Author: cdce8p <30130371+cdce8p@users.noreply.github.com>
Date:   Mon Jan 18 16:41:02 2021 +0100

    Add argument groups

commit 78b96bb
Author: cdce8p <30130371+cdce8p@users.noreply.github.com>
Date:   Mon Jan 18 16:38:23 2021 +0100

    Reorder arguments

commit 0af008b
Author: cdce8p <30130371+cdce8p@users.noreply.github.com>
Date:   Mon Jan 18 16:28:14 2021 +0100

    Change code formatting - argparser

    * No code changes!
  • Loading branch information
@raimon49
raimon49 committed Jan 23, 2021
1 parent 606ff8b commit 90717bf
Show file tree
Hide file tree
Showing 5 changed files with 498 additions and 318 deletions.
6 changes: 6 additions & 0 deletions .gitignore
View file
Original file line number Diff line number Diff line change
Expand Up @@ -104,3 +104,9 @@ ENV/
# ignore files to run in docker
docker/*
!docker/.gitkeep

# Windows
[Dd]esktop.ini

# macOS
.DS_Store
249 changes: 130 additions & 119 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -10,29 +10,32 @@ Dump the software license list of Python packages installed with pip.
* [Installation](#installation)
* [Usage](#usage)
* [Command\-Line Options](#command-line-options)
* [Option: from](#option-from)
* [Option: with\-system](#option-with-system)
* [Option: with\-authors](#option-with-authors)
* [Option: with\-urls](#option-with-urls)
* [Option: with\-description](#option-with-description)
* [Option: with\-license\-file](#option-with-license-file)
* [Option: ignore\-packages](#option-ignore-packages)
* [Option: order](#option-order)
* [Option: format](#option-format)
* [Markdown](#markdown)
* [reST](#rest)
* [Confluence](#confluence)
* [HTML](#html)
* [JSON](#json)
* [JSON LicenseFinder](#json-licensefinder)
* [CSV](#csv)
* [Plain Vertical](#plain-vertical)
* [Option: summary](#option-summary)
* [Option: output\-file](#option-output-file)
* [Option: filter\-strings](#option-filter-strings)
* [Option: filter\-code\-page](#option-filter-code-page)
* [Option: fail\-on](#option-fail-on)
* [Option: allow\-only](#option-allow-only)
* [Common options](#common-options)
* [Option: from](#option-from)
* [Option: order](#option-order)
* [Option: format](#option-format)
* [Markdown](#markdown)
* [reST](#rest)
* [Confluence](#confluence)
* [HTML](#html)
* [JSON](#json)
* [JSON LicenseFinder](#json-licensefinder)
* [CSV](#csv)
* [Plain Vertical](#plain-vertical)
* [Option: summary](#option-summary)
* [Option: output\-file](#option-output-file)
* [Option: ignore\-packages](#option-ignore-packages)
* [Format options](#format-options)
* [Option: with\-system](#option-with-system)
* [Option: with\-authors](#option-with-authors)
* [Option: with\-urls](#option-with-urls)
* [Option: with\-description](#option-with-description)
* [Option: with\-license\-file](#option-with-license-file)
* [Option: filter\-strings](#option-filter-strings)
* [Option: filter\-code\-page](#option-filter-code-page)
* [Verify options](#verify-options)
* [Option: fail\-on](#option-fail-on)
* [Option: allow\-only](#option-allow-only)
* [More Information](#more-information)
* [Dockerfile](#dockerfile)
* [About UnicodeEncodeError](#about-unicodeencodeerror)
Expand Down Expand Up @@ -81,7 +84,9 @@ Execute the command with your venv (or virtualenv) environment.

## Command-Line Options

### Option: from
### Common options

#### Option: from

By default, this tool finds the license from [Trove Classifiers](https://pypi.org/classifiers/) or package Metadata. Some Python packages declare their license only in Trove Classifiers.

Expand Down Expand Up @@ -120,85 +125,7 @@ To list license information from both metadata and classifier, use `--from=all`.
* The `mix` keyword is prepared as alias of `mixed`.
* Default behavior in this tool

### Option: with-system

By default, system packages such as `pip` and `setuptools` are ignored.

If you want to output all including system package, use the `--with-system` option.

```bash
(venv) $ pip-licenses --with-system
Name Version License
Django 2.0.2 BSD
PTable 0.9.2 BSD (3 clause)
pip 9.0.1 MIT
pip-licenses 1.0.0 MIT License
pytz 2017.3 MIT
setuptools 38.5.0 UNKNOWN
```

### Option: with-authors

When executed with the `--with-authors` option, output with author of the package.

```bash
(venv) $ pip-licenses --with-authors
Name Version License Author
Django 2.0.2 BSD Django Software Foundation
pytz 2017.3 MIT Stuart Bishop
```

### Option: with-urls

For packages without Metadata, the license is output as `UNKNOWN`. To get more package information, use the `--with-urls` option.

```bash
(venv) $ pip-licenses --with-urls
Name Version License URL
Django 2.0.2 BSD https://www.djangoproject.com/
pytz 2017.3 MIT http://pythonhosted.org/pytz
```

### Option: with-description

When executed with the `--with-description` option, output with short description of the package.

```bash
(venv) $ pip-licenses --with-description
Name Version License Description
Django 2.0.2 BSD A high-level Python Web framework that encourages rapid development and clean, pragmatic design.
pytz 2017.3 MIT World timezone definitions, modern and historical
```

### Option: with-license-file

When executed with the `--with-license-file` option, output the location of the package's license file on disk and the full contents of that file. Due to the length of these fields, this option is best paired with `--format=json`.

If you also want to output the file `NOTICE` distributed under Apache License etc., specify the `--with-notice-file` option additionally.

**Note:** If you want to keep the license file path secret, specify `--no-license-path` option together.

### Option: ignore-packages

When executed with the `--ignore-packages` option, ignore the package specified by argument from list output.

```bash
(venv) $ pip-licenses --ignore-packages django
Name Version License
pytz 2017.3 MIT
```

Package names of arguments can be separated by spaces.

```bash
(venv) $ pip-licenses --with-system --ignore-packages django pip pip-licenses
Name Version License
PTable 0.9.2 BSD (3 clause)
pytz 2017.3 MIT
setuptools 38.5.0 UNKNOWN
```

### Option: order
#### Option: order

By default, it is ordered by package name.

Expand All @@ -208,11 +135,11 @@ If you give arguments to the `--order` option, you can output in other sorted or
(venv) $ pip-licenses --order=license
```

### Option: format
#### Option: format

By default, it is output to the `plain` format.

#### Markdown
##### Markdown

When executed with the `--format=markdown` option, you can output list in markdown format. The `m` `md` keyword is prepared as alias of `markdown`.

Expand All @@ -231,7 +158,7 @@ When inserted in a markdown document, it is rendered as follows:
| Django | 2.0.2 | BSD |
| pytz | 2017.3 | MIT |

#### reST
##### reST

When executed with the `--format=rst` option, you can output list in "[Grid tables](http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html#grid-tables)" of reStructuredText format. The `r` `rest` keyword is prepared as alias of `rst`.

Expand All @@ -246,7 +173,7 @@ When executed with the `--format=rst` option, you can output list in "[Grid tabl
+--------+---------+---------+
```

#### Confluence
##### Confluence

When executed with the `--format=confluence` option, you can output list in [Confluence (or JIRA) Wiki markup](https://confluence.atlassian.com/doc/confluence-wiki-markup-251003035.html#ConfluenceWikiMarkup-Tables) format. The `c` keyword is prepared as alias of `confluence`.

Expand All @@ -257,7 +184,7 @@ When executed with the `--format=confluence` option, you can output list in [Con
| pytz | 2017.3 | MIT |
```

#### HTML
##### HTML

When executed with the `--format=html` option, you can output list in HTML table format. The `h` keyword is prepared as alias of `html`.

Expand All @@ -282,7 +209,7 @@ When executed with the `--format=html` option, you can output list in HTML table
</table>
```

#### JSON
##### JSON

When executed with the `--format=json` option, you can output list in JSON format easily allowing post-processing. The `j` keyword is prepared as alias of `json`.

Expand All @@ -303,10 +230,9 @@ When executed with the `--format=json` option, you can output list in JSON forma
"Version": "2017.3"
}
]

```

#### JSON LicenseFinder
##### JSON LicenseFinder

When executed with the `--format=json-license-finder` option, you can output list in JSON format that is identical to [LicenseFinder](https://github.com/pivotal/LicenseFinder). The `jlf` keyword is prepared as alias of `jlf`.
This makes pip-licenses a drop-in replacement for LicenseFinder.
Expand All @@ -327,7 +253,7 @@ This makes pip-licenses a drop-in replacement for LicenseFinder.

```

#### CSV
##### CSV

When executed with the `--format=csv` option, you can output list in quoted CSV format. Useful when you want to copy/paste the output to an Excel sheet.

Expand All @@ -338,7 +264,7 @@ When executed with the `--format=csv` option, you can output list in quoted CSV
"pytz","2017.3","MIT"
```

#### Plain Vertical
##### Plain Vertical

When executed with the `--format=plain-vertical` option, you can output a simple plain vertical output that is similar to Angular CLI's
[--extractLicenses flag](https://angular.io/cli/build#options). This format minimizes rightward drift.
Expand Down Expand Up @@ -371,7 +297,7 @@ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.
```

### Option: summary
#### Option: summary

When executed with the `--summary` option, you can output a summary of each license.

Expand All @@ -384,7 +310,7 @@ When executed with the `--summary` option, you can output a summary of each lice

**Note:** When using this option, only `--order=count` or `--order=license` has an effect for the `--order` option. And using `--with-authors` and `--with-urls` will be ignored.

### Option: output\-file
#### Option: output\-file

When executed with the `--output-file` option, write the result to the path specified by the argument.

Expand All @@ -393,15 +319,99 @@ When executed with the `--output-file` option, write the result to the path spec
created path: /tmp/output.rst
```

### Option: filter\-strings
#### Option: ignore-packages

When executed with the `--ignore-packages` option, ignore the package specified by argument from list output.

```bash
(venv) $ pip-licenses --ignore-packages django
Name Version License
pytz 2017.3 MIT
```

Package names of arguments can be separated by spaces.

```bash
(venv) $ pip-licenses --with-system --ignore-packages django pip pip-licenses
Name Version License
PTable 0.9.2 BSD (3 clause)
pytz 2017.3 MIT
setuptools 38.5.0 UNKNOWN
```


### Format options

#### Option: with-system

By default, system packages such as `pip` and `setuptools` are ignored.

If you want to output all including system package, use the `--with-system` option.

```bash
(venv) $ pip-licenses --with-system
Name Version License
Django 2.0.2 BSD
PTable 0.9.2 BSD (3 clause)
pip 9.0.1 MIT
pip-licenses 1.0.0 MIT License
pytz 2017.3 MIT
setuptools 38.5.0 UNKNOWN
```

#### Option: with-authors

When executed with the `--with-authors` option, output with author of the package.

```bash
(venv) $ pip-licenses --with-authors
Name Version License Author
Django 2.0.2 BSD Django Software Foundation
pytz 2017.3 MIT Stuart Bishop
```

#### Option: with-urls

For packages without Metadata, the license is output as `UNKNOWN`. To get more package information, use the `--with-urls` option.

```bash
(venv) $ pip-licenses --with-urls
Name Version License URL
Django 2.0.2 BSD https://www.djangoproject.com/
pytz 2017.3 MIT http://pythonhosted.org/pytz
```

#### Option: with-description

When executed with the `--with-description` option, output with short description of the package.

```bash
(venv) $ pip-licenses --with-description
Name Version License Description
Django 2.0.2 BSD A high-level Python Web framework that encourages rapid development and clean, pragmatic design.
pytz 2017.3 MIT World timezone definitions, modern and historical
```

#### Option: with-license-file

When executed with the `--with-license-file` option, output the location of the package's license file on disk and the full contents of that file. Due to the length of these fields, this option is best paired with `--format=json`.

If you also want to output the file `NOTICE` distributed under Apache License etc., specify the `--with-notice-file` option additionally.

**Note:** If you want to keep the license file path secret, specify `--no-license-path` option together.

#### Option: filter\-strings

Some package data contains Unicode characters which might cause problems for certain output formats (in particular ReST tables). If this filter is enabled, all characters which cannot be encoded with a given code page (see `--filter-code-page`) will be removed from any input strings (e.g. package name, description).

### Option: filter\-code\-page
#### Option: filter\-code\-page

If the input strings are filtered (see `--filter-strings`), you can specify the applied code page (default `latin-1`). A list of all available code pages can be found [codecs module document](https://docs.python.org/3/library/codecs.html#standard-encodings).

### Option: fail\-on

### Verify options

#### Option: fail\-on

Fail (exit with code 1) on the first occurrence of the licenses of the semicolon-separated list

Expand All @@ -425,7 +435,7 @@ $ echo $?
$ pip-licenses --fail-on="Python Software Foundation License, MIT License;"
```

### Option: allow\-only
#### Option: allow\-only

Fail (exit with code 1) on the first occurrence of the licenses not in the semicolon-separated list

Expand All @@ -444,6 +454,7 @@ $ pip-licenses | grep keyring
$ pip-licenses --allow-only="Python Software Foundation License, MIT License;"
```


### More Information

Other, please make sure to execute the `--help` option.
Expand Down
Loading

0 comments on commit 90717bf

Please sign in to comment.