From 8e4ba6f0e4835026e85fca81faba267c95eb31fc Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?R=C3=A9mi=20Alvergnat?= Date: Sat, 6 Feb 2021 01:03:25 +0100 Subject: [PATCH] docs: lighten README and update doc index page --- README.md | 140 ------------------------------ docs/configuration.md | 2 +- docs/index.md | 196 ++++++++++++++++++++++-------------------- 3 files changed, 103 insertions(+), 235 deletions(-) diff --git a/README.md b/README.md index 9b65ea6..5f87fb6 100644 --- a/README.md +++ b/README.md @@ -33,146 +33,6 @@ For example, GuessIt can do the following: More information are available at [guessit.io](http://guessit.io/). -Migration note ------ - -GuessIt 2 has been rewriten from scratch. GuessIt is now a release name -parser only, and support for additional features like hashes -computations has been dropped. - -To migrate from guessit `0.x` or `1.x` to `guessit 2.x`, please read -[migration.md](./docs/migration.md). - -To migrate from guessit `2.x` to `3.x`, please read -[migration2to3.md](./docs/migration2to3.md). - -Install ------ - -Installing GuessIt is simple with [pip](http://www.pip-installer.org/): - - $ pip install guessit - -You can also [install GuessIt from sources](./docs/sources.md) - -Usage ------ - -GuessIt can be used from command line: - - $ guessit - usage: guessit [-h] [-t TYPE] [-n] [-Y] [-D] [-L ALLOWED_LANGUAGES] - [-C ALLOWED_COUNTRIES] [-E] [-T EXPECTED_TITLE] - [-G EXPECTED_GROUP] [--includes INCLUDES] - [--excludes EXCLUDES] [-f INPUT_FILE] [-v] - [-P SHOW_PROPERTY] [-a] [-s] [-l] [-j] [-y] [-c CONFIG] - [--no-user-config] [--no-default-config] [-p] [-V] - [--version] - [filename [filename ...]] - - positional arguments: - filename Filename or release name to guess - - optional arguments: - -h, --help show this help message and exit - - Naming: - -t TYPE, --type TYPE The suggested file type: movie, episode. If undefined, - type will be guessed. - -n, --name-only Parse files as name only, considering "/" and "\" like - other separators. - -Y, --date-year-first - If short date is found, consider the first digits as - the year. - -D, --date-day-first If short date is found, consider the second digits as - the day. - -L ALLOWED_LANGUAGES, --allowed-languages ALLOWED_LANGUAGES - Allowed language (can be used multiple times) - -C ALLOWED_COUNTRIES, --allowed-countries ALLOWED_COUNTRIES - Allowed country (can be used multiple times) - -E, --episode-prefer-number - Guess "serie.213.avi" as the episode 213. Without this - option, it will be guessed as season 2, episode 13 - -T EXPECTED_TITLE, --expected-title EXPECTED_TITLE - Expected title to parse (can be used multiple times) - -G EXPECTED_GROUP, --expected-group EXPECTED_GROUP - Expected release group (can be used multiple times) - --includes INCLUDES List of properties to be detected - --excludes EXCLUDES List of properties to be ignored - - Input: - -f INPUT_FILE, --input-file INPUT_FILE - Read filenames from an input text file. File should - use UTF-8 charset. - - Output: - -v, --verbose Display debug output - -P SHOW_PROPERTY, --show-property SHOW_PROPERTY - Display the value of a single property (title, series, - video_codec, year, ...) - -a, --advanced Display advanced information for filename guesses, as - json output - -s, --single-value Keep only first value found for each property - -l, --enforce-list Wrap each found value in a list even when property has - a single value - -j, --json Display information for filename guesses as json - output - -y, --yaml Display information for filename guesses as yaml - output - - Configuration: - -c CONFIG, --config CONFIG - Filepath to configuration file. Configuration file - contains the same options as those from command line - options, but option names have "-" characters replaced - with "_". This configuration will be merged with - default and user configuration files. - --no-user-config Disable user configuration. If not defined, guessit - tries to read configuration files at - ~/.guessit/options.(json|yml|yaml) and - ~/.config/guessit/options.(json|yml|yaml) - --no-default-config Disable default configuration. This should be done - only if you are providing a full configuration through - user configuration or --config option. If no - "advanced_config" is provided by another configuration - file, it will still be loaded from default - configuration. - - Information: - -p, --properties Display properties that can be guessed. - -V, --values Display property values that can be guessed. - --version Display the guessit version. - -It can also be used as a python module: - - >>> from guessit import guessit - >>> guessit('Treme.1x03.Right.Place,.Wrong.Time.HDTV.XviD-NoTV.avi') - MatchesDict([('title', 'Treme'), ('season', 1), ('episode', 3), ('episode_title', 'Right Place, Wrong Time'), ('source', 'HDTV'), ('video_codec', 'Xvid'), ('release_group', 'NoTV'), ('container', 'avi'), ('mimetype', 'video/x-msvideo'), ('type', 'episode')]) - -`MatchesDict` is a dict that keeps matches ordering. - -Command line options can be given as dict or string to the second argument. - -Docker ------- - -GuessIt is also available on [Docker Hub](https://hub.docker.com/r/guessit/guessit/) as a Docker Image.: - - $ docker run -it guessit/guessit "Treme.1x03.Right.Place,.Wrong.Time.HDTV.XviD-NoTV.avi" - For: Treme.1x03.Right.Place,.Wrong.Time.HDTV.XviD-NoTV.avi - GuessIt found: { - "title": "Treme", - "season": 1, - "episode": 3, - "episode_title": "Right Place, Wrong Time", - "source": "HDTV", - "video_codec": "Xvid", - "release_group": "NoTV", - "container": "avi", - "mimetype": "video/x-msvideo", - "type": "episode" - } - Support ------- diff --git a/docs/configuration.md b/docs/configuration.md index 0b75b95..8eab056 100644 --- a/docs/configuration.md +++ b/docs/configuration.md @@ -38,4 +38,4 @@ used. We're willing to keep it backwards compatible, but in order to enhance Guessit, these parameters might change without prior notice. - [config/options.json]: https://github.com/guessit-io/guessit/blob/develop/guessit/config/options.json/ \ No newline at end of file + [config/options.json]: https://github.com/guessit-io/guessit/blob/master/guessit/config/options.json/ \ No newline at end of file diff --git a/docs/index.md b/docs/index.md index c8b23d8..16aa626 100644 --- a/docs/index.md +++ b/docs/index.md @@ -1,10 +1,11 @@ GuessIt ======= -[![Latest Version](http://img.shields.io/pypi/v/guessit.svg)](https://pypi.python.org/pypi/guessit) -[![LGPLv3 License](http://img.shields.io/badge/license-LGPLv3-blue.svg)]() +[![Latest Version](https://img.shields.io/pypi/v/guessit.svg)](https://pypi.python.org/pypi/guessit) +[![LGPLv3 License](https://img.shields.io/badge/license-LGPLv3-blue.svg)]() [![Build Status](https://img.shields.io/github/workflow/status/guessit-io/guessit/ci)](https://github.com/guessit-io/guessit/actions?query=workflow%3Aci) -[![Coveralls](http://img.shields.io/coveralls/guessit-io/guessit/master.svg)](https://coveralls.io/github/guessit-io/guessit?branch=master) +[![Coveralls](https://img.shields.io/coveralls/guessit-io/guessit/master.svg)](https://coveralls.io/github/guessit-io/guessit?branch=master) +[![semantic-release](https://img.shields.io/badge/%20%20%F0%9F%93%A6%F0%9F%9A%80-semantic--release-e10079.svg)](https://github.com/relekang/python-semantic-release) GuessIt is a python library that extracts as much information as possible from a video filename. @@ -31,115 +32,122 @@ For example, GuessIt can do the following: } Migration note --------------- +----- In GuessIt 3, some properties and values were renamed in order to keep consistency and to be more intuitive. -To migrate from guessit `2.x` to guessit `3.x`, please read the migration page\. To migrate from guessit `0.x` or `1.x` to guessit `2.x`, please read the migration page\. +To migrate from guessit `2.x` to `3.x`, please read +[migration2to3.md](./migration2to3.md). + +To migrate from guessit `0.x` or `1.x` to `guessit 2.x`, please read +[migration.md](./migration.md). Install -------- +----- Installing GuessIt is simple with [pip](http://www.pip-installer.org/): - $ pip install guessit +```bash +pip install guessit +``` -You can also install from sources \. +You can also [install GuessIt from sources](./sources.md) Usage ----- GuessIt can be used from command line: - $ guessit - usage: guessit [-h] [-t TYPE] [-n] [-Y] [-D] [-L ALLOWED_LANGUAGES] - [-C ALLOWED_COUNTRIES] [-E] [-T EXPECTED_TITLE] - [-G EXPECTED_GROUP] [--includes INCLUDES] [--excludes EXCLUDES] - [-f INPUT_FILE] [-v] [-P SHOW_PROPERTY] [-a] [-s] [-l] [-j] - [-y] [-i] [-c CONFIG] [--no-user-config] [--no-default-config] - [-p] [-V] [--version] - [filename [filename ...]] - - positional arguments: - filename Filename or release name to guess - - optional arguments: - -h, --help show this help message and exit - - Naming: - -t TYPE, --type TYPE The suggested file type: movie, episode. If undefined, - type will be guessed. - -n, --name-only Parse files as name only, considering "/" and "\" like - other separators. - -Y, --date-year-first - If short date is found, consider the first digits as - the year. - -D, --date-day-first If short date is found, consider the second digits as - the day. - -L ALLOWED_LANGUAGES, --allowed-languages ALLOWED_LANGUAGES - Allowed language (can be used multiple times) - -C ALLOWED_COUNTRIES, --allowed-countries ALLOWED_COUNTRIES - Allowed country (can be used multiple times) - -E, --episode-prefer-number - Guess "serie.213.avi" as the episode 213. Without this - option, it will be guessed as season 2, episode 13 - -T EXPECTED_TITLE, --expected-title EXPECTED_TITLE - Expected title to parse (can be used multiple times) - -G EXPECTED_GROUP, --expected-group EXPECTED_GROUP - Expected release group (can be used multiple times) - --includes INCLUDES List of properties to be detected - --excludes EXCLUDES List of properties to be ignored - - Input: - -f INPUT_FILE, --input-file INPUT_FILE - Read filenames from an input text file. File should - use UTF-8 charset. - - Output: - -v, --verbose Display debug output - -P SHOW_PROPERTY, --show-property SHOW_PROPERTY - Display the value of a single property (title, series, - video_codec, year, ...) - -a, --advanced Display advanced information for filename guesses, as - json output - -s, --single-value Keep only first value found for each property - -l, --enforce-list Wrap each found value in a list even when property has - a single value - -j, --json Display information for filename guesses as json - output - -y, --yaml Display information for filename guesses as yaml - output - -i, --output-input-string - Add input_string property in the output - - Configuration: - -c CONFIG, --config CONFIG - Filepath to configuration file. Configuration file - contains the same options as those from command line - options, but option names have "-" characters replaced - with "_". This configuration will be merged with - default and user configuration files. - --no-user-config Disable user configuration. If not defined, guessit - tries to read configuration files at - ~/.guessit/options.(json|yml|yaml) and - ~/.config/guessit/options.(json|yml|yaml) - --no-default-config Disable default configuration. This should be done - only if you are providing a full configuration through - user configuration or --config option. If no - "advanced_config" is provided by another configuration - file, it will still be loaded from default - configuration. - - Information: - -p, --properties Display properties that can be guessed. - -V, --values Display property values that can be guessed. - --version Display the guessit version. +``` +usage: guessit [-h] [-t TYPE] [-n] [-Y] [-D] [-L ALLOWED_LANGUAGES] + [-C ALLOWED_COUNTRIES] [-E] [-T EXPECTED_TITLE] + [-G EXPECTED_GROUP] [--includes INCLUDES] [--excludes EXCLUDES] + [-f INPUT_FILE] [-v] [-P SHOW_PROPERTY] [-a] [-s] [-l] [-j] + [-y] [-i] [-c CONFIG] [--no-user-config] [--no-default-config] + [-p] [-V] [--version] + [filename [filename ...]] + +positional arguments: + filename Filename or release name to guess + +optional arguments: + -h, --help show this help message and exit + +Naming: + -t TYPE, --type TYPE The suggested file type: movie, episode. If undefined, + type will be guessed. + -n, --name-only Parse files as name only, considering "/" and "\" like + other separators. + -Y, --date-year-first + If short date is found, consider the first digits as + the year. + -D, --date-day-first If short date is found, consider the second digits as + the day. + -L ALLOWED_LANGUAGES, --allowed-languages ALLOWED_LANGUAGES + Allowed language (can be used multiple times) + -C ALLOWED_COUNTRIES, --allowed-countries ALLOWED_COUNTRIES + Allowed country (can be used multiple times) + -E, --episode-prefer-number + Guess "serie.213.avi" as the episode 213. Without this + option, it will be guessed as season 2, episode 13 + -T EXPECTED_TITLE, --expected-title EXPECTED_TITLE + Expected title to parse (can be used multiple times) + -G EXPECTED_GROUP, --expected-group EXPECTED_GROUP + Expected release group (can be used multiple times) + --includes INCLUDES List of properties to be detected + --excludes EXCLUDES List of properties to be ignored + +Input: + -f INPUT_FILE, --input-file INPUT_FILE + Read filenames from an input text file. File should + use UTF-8 charset. + +Output: + -v, --verbose Display debug output + -P SHOW_PROPERTY, --show-property SHOW_PROPERTY + Display the value of a single property (title, series, + video_codec, year, ...) + -a, --advanced Display advanced information for filename guesses, as + json output + -s, --single-value Keep only first value found for each property + -l, --enforce-list Wrap each found value in a list even when property has + a single value + -j, --json Display information for filename guesses as json + output + -y, --yaml Display information for filename guesses as yaml + output + -i, --output-input-string + Add input_string property in the output + +Configuration: + -c CONFIG, --config CONFIG + Filepath to configuration file. Configuration file + contains the same options as those from command line + options, but option names have "-" characters replaced + with "_". This configuration will be merged with + default and user configuration files. + --no-user-config Disable user configuration. If not defined, guessit + tries to read configuration files at + ~/.guessit/options.(json|yml|yaml) and + ~/.config/guessit/options.(json|yml|yaml) + --no-default-config Disable default configuration. This should be done + only if you are providing a full configuration through + user configuration or --config option. If no + "advanced_config" is provided by another configuration + file, it will still be loaded from default + configuration. + +Information: + -p, --properties Display properties that can be guessed. + -V, --values Display property values that can be guessed. + --version Display the guessit version. +``` It can also be used as a python module: >>> from guessit import guessit - >>> guessit('Treme.1x03.Right.Place,.Wrong.Time.HDTV.XviD-NoTV.avi') # doctest: +ALLOW_UNICODE - MatchesDict([('title', 'Treme'), ('season', 1), ('episode', 3), ('episode_title', 'Right Place, Wrong Time'), ('source', 'HDTV'), ('video_codec', 'XviD'), ('release_group', 'NoTV'), ('container', 'avi'), ('mimetype', 'video/x-msvideo'), ('type', 'episode')]) + >>> guessit('Treme.1x03.Right.Place,.Wrong.Time.HDTV.XviD-NoTV.avi') + MatchesDict([('title', 'Treme'), ('season', 1), ('episode', 3), ('episode_title', 'Right Place, Wrong Time'), ('source', 'HDTV'), ('video_codec', 'Xvid'), ('release_group', 'NoTV'), ('container', 'avi'), ('mimetype', 'video/x-msvideo'), ('type', 'episode')]) `MatchesDict` is a dict that keeps matches ordering. @@ -148,7 +156,7 @@ Command line options can be given as dict or string to the second argument. Configuration ------------- -Find more about Guessit configuration at configuration page\. +Find more about Guessit configuration at [configuration page](./configuration.md). REST API --------