GuessIt
=======

.. image:: http://img.shields.io/pypi/v/guessit.svg
    :target: https://pypi.python.org/pypi/guessit
    :alt: Latest Version

.. image:: http://img.shields.io/badge/license-LGPLv3-blue.svg
    :target: https://pypi.python.org/pypi/guessit
    :alt: LGPLv3 License

.. image:: http://img.shields.io/travis/guessit-io/guessit.svg
    :target: https://travis-ci.org/guessit-io/guessit
    :alt: Build Status

.. image:: http://img.shields.io/coveralls/guessit-io/guessit/master.svg
    :target: https://coveralls.io/github/guessit-io/guessit?branch=master
    :alt: Coveralls

.. image:: https://img.shields.io/badge/Hu-Board-7965cc.svg
    :target: https://huboard.com/guessit-io/guessit
    :alt: HuBoard


GuessIt is a python library that extracts as much information as possible from a video filename.

It has a very powerful matcher that allows to guess properties from a video using its filename only.
This matcher works with both movies and tv shows episodes.

For example, GuessIt can do the following::

    $ 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"
    }

More information are available at `ReadTheDocs <http://guessit.readthedocs.org/>`_.

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.rst <https://github.com/guessit-io/guessit/blob/master/docs/migration.rst>`_.

To migrate from guessit ``2.x`` to ``3.x``, please read `migration2to3.rst <https://github.com/guessit-io/guessit/blob/master/docs/migration2to3.rst>`_.

Install
-------

Installing GuessIt is simple with `pip <http://www.pip-installer.org/>`_::

    $ pip install guessit

You can also `install GuessIt from sources <https://github.com/guessit-io/guessit/blob/master/docs/sources.rst>`_

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
-------

This project is hosted on `GitHub <https://github.com/guessit-io/guessit>`_. Feel free to open an issue if you think you
have found a bug or something is missing in guessit.

GuessIt relies on `Rebulk <https://github.com/Toilal/rebulk>`_ project for pattern and rules registration.

License
-------

GuessIt is licensed under the `LGPLv3 license <http://www.gnu.org/licenses/lgpl.html>`_.