Release 2.0.3

New score equations

.coveragerc

@@ -0,0 +1,8 @@
+[report]
+exclude_lines =
+    pragma: no cover
+    raise NotImplementedError
+    def __repr__
+    if __name__ == .__main__.:
+omit =
+    subliminal/cli.py

.gitignore

@@ -1,43 +1,64 @@
-*.py[co]
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
 
-# Packages
-*.egg
-*.egg-info
-dist
-build
-eggs
-parts
-bin
-var
-sdist
-develop-eggs
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+env/
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+*.egg-info/
 .installed.cfg
+*.egg
+
+# PyInstaller
+#  Usually these files are written by a python script from a template
+#  before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
 
 # Installer logs
 pip-log.txt
+pip-delete-this-directory.txt
 
 # Unit test / coverage reports
+htmlcov/
+.tox/
 .coverage
-.tox
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*,cover
 
 # Translations
 *.mo
+*.pot
 
-# Mr Developer
-.mr.developer.cfg
+# Django stuff:
+*.log
 
-# Pydev
-.project
-.pydevproject
-.settings
+# Sphinx documentation
+docs/_build/
 
-# Rope
-.ropeproject
+# PyBuilder
+target/
 
-# Sphinx
-docs/_build
+# Pycharm
+.idea
 
-# Subliminal unittests
-tests/*.srt
-tests/*_files
-tests/*_cache
+# Subliminal
+tests/data/mkv/

.gitmodules

@@ -1,3 +0,0 @@
-[submodule "docs/_themes"]
-	path = docs/_themes
-	url = git://github.com/Diaoul/diaoul-sphinx-themes.git

.travis.yml

@@ -1,9 +1,49 @@
+sudo: false
+
 language: python
+
 python:
   - "2.7"
+  - "3.3"
+  - "3.4"
+  - "3.5"
+
+env:
+  - PARSER=native
+  - PARSER=lxml
+
+addons:
+  apt:
+    packages:
+    - unrar
+
+matrix:
+  include:
+    - python: "3.5"
+      env:
+        - PARSER=native
+        - VCR_RECORD_MODE=all
+        - PYTEST_ADDOPTS="-m integration"
+  allow_failures:
+    - python: "3.5"
+      env:
+        - PARSER=native
+        - VCR_RECORD_MODE=all
+        - PYTEST_ADDOPTS="-m integration"
+
+cache:
+  directories:
+    - $HOME/.cache/pip
+    - tests/data/mkv
+
+before_cache:
+  - rm -f $HOME/.cache/pip/log/debug.log
+
 install:
-  - pip install -r requirements.txt --use-mirrors
-  - pip install -r optional-requirements.txt --use-mirrors
-script: python setup.py test
-notifications:
-  irc: "irc.freenode.org#subliminal"
+  - pip install -e .[test]
+  - if [ $PARSER = "lxml" ]; then pip install lxml; fi
+  - pip install coveralls
+
+script: python setup.py test --addopts "--cov subliminal --verbose $PYTEST_ADDOPTS"
+
+after_success: coveralls

CONTRIBUTING.md

@@ -0,0 +1,19 @@
+Contributing
+============
+
+Issues
+------
+Issues are intended for bug report and feature requests. For any bug report please make sure to include the complete
+stack trace and DEBUG level logs as well as reproduce steps.
+
+If you use the CLI, you can create a debug log file with `subliminal --debug [...] 2> debug.log`.
+
+Pull Requests
+-------------
+You can contribute code and documentation with pull requests. Any code contribution must be unit tested and the pull
+request open against the *develop* branch.
+
+Translations
+------------
+Contribution to translations can be made on [subliminal's transifex page](https://www.transifex.com/subliminal/subliminal/)
+Subliminal is configured to work with [transifex-client](http://docs.transifex.com/client/)

COPYING

@@ -1,674 +0,0 @@
-                    GNU GENERAL PUBLIC LICENSE
-                       Version 3, 29 June 2007
-
- Copyright (C) 2007 Free Software Foundation, Inc. <http://fsf.org/>
- Everyone is permitted to copy and distribute verbatim copies
- of this license document, but changing it is not allowed.
-
-                            Preamble
-
-  The GNU General Public License is a free, copyleft license for
-software and other kinds of works.
-
-  The licenses for most software and other practical works are designed
-to take away your freedom to share and change the works.  By contrast,
-the GNU General Public License is intended to guarantee your freedom to
-share and change all versions of a program--to make sure it remains free
-software for all its users.  We, the Free Software Foundation, use the
-GNU General Public License for most of our software; it applies also to
-any other work released this way by its authors.  You can apply it to
-your programs, too.
-
-  When we speak of free software, we are referring to freedom, not
-price.  Our General Public Licenses are designed to make sure that you
-have the freedom to distribute copies of free software (and charge for
-them if you wish), that you receive source code or can get it if you
-want it, that you can change the software or use pieces of it in new
-free programs, and that you know you can do these things.
-
-  To protect your rights, we need to prevent others from denying you
-these rights or asking you to surrender the rights.  Therefore, you have
-certain responsibilities if you distribute copies of the software, or if
-you modify it: responsibilities to respect the freedom of others.
-
-  For example, if you distribute copies of such a program, whether
-gratis or for a fee, you must pass on to the recipients the same
-freedoms that you received.  You must make sure that they, too, receive
-or can get the source code.  And you must show them these terms so they
-know their rights.
-
-  Developers that use the GNU GPL protect your rights with two steps:
-(1) assert copyright on the software, and (2) offer you this License
-giving you legal permission to copy, distribute and/or modify it.
-
-  For the developers' and authors' protection, the GPL clearly explains
-that there is no warranty for this free software.  For both users' and
-authors' sake, the GPL requires that modified versions be marked as
-changed, so that their problems will not be attributed erroneously to
-authors of previous versions.
-
-  Some devices are designed to deny users access to install or run
-modified versions of the software inside them, although the manufacturer
-can do so.  This is fundamentally incompatible with the aim of
-protecting users' freedom to change the software.  The systematic
-pattern of such abuse occurs in the area of products for individuals to
-use, which is precisely where it is most unacceptable.  Therefore, we
-have designed this version of the GPL to prohibit the practice for those
-products.  If such problems arise substantially in other domains, we
-stand ready to extend this provision to those domains in future versions
-of the GPL, as needed to protect the freedom of users.
-
-  Finally, every program is threatened constantly by software patents.
-States should not allow patents to restrict development and use of
-software on general-purpose computers, but in those that do, we wish to
-avoid the special danger that patents applied to a free program could
-make it effectively proprietary.  To prevent this, the GPL assures that
-patents cannot be used to render the program non-free.
-
-  The precise terms and conditions for copying, distribution and
-modification follow.
-
-                       TERMS AND CONDITIONS
-
-  0. Definitions.
-
-  "This License" refers to version 3 of the GNU General Public License.
-
-  "Copyright" also means copyright-like laws that apply to other kinds of
-works, such as semiconductor masks.
-
-  "The Program" refers to any copyrightable work licensed under this
-License.  Each licensee is addressed as "you".  "Licensees" and
-"recipients" may be individuals or organizations.
-
-  To "modify" a work means to copy from or adapt all or part of the work
-in a fashion requiring copyright permission, other than the making of an
-exact copy.  The resulting work is called a "modified version" of the
-earlier work or a work "based on" the earlier work.
-
-  A "covered work" means either the unmodified Program or a work based
-on the Program.
-
-  To "propagate" a work means to do anything with it that, without
-permission, would make you directly or secondarily liable for
-infringement under applicable copyright law, except executing it on a
-computer or modifying a private copy.  Propagation includes copying,
-distribution (with or without modification), making available to the
-public, and in some countries other activities as well.
-
-  To "convey" a work means any kind of propagation that enables other
-parties to make or receive copies.  Mere interaction with a user through
-a computer network, with no transfer of a copy, is not conveying.
-
-  An interactive user interface displays "Appropriate Legal Notices"
-to the extent that it includes a convenient and prominently visible
-feature that (1) displays an appropriate copyright notice, and (2)
-tells the user that there is no warranty for the work (except to the
-extent that warranties are provided), that licensees may convey the
-work under this License, and how to view a copy of this License.  If
-the interface presents a list of user commands or options, such as a
-menu, a prominent item in the list meets this criterion.
-
-  1. Source Code.
-
-  The "source code" for a work means the preferred form of the work
-for making modifications to it.  "Object code" means any non-source
-form of a work.
-
-  A "Standard Interface" means an interface that either is an official
-standard defined by a recognized standards body, or, in the case of
-interfaces specified for a particular programming language, one that
-is widely used among developers working in that language.
-
-  The "System Libraries" of an executable work include anything, other
-than the work as a whole, that (a) is included in the normal form of
-packaging a Major Component, but which is not part of that Major
-Component, and (b) serves only to enable use of the work with that
-Major Component, or to implement a Standard Interface for which an
-implementation is available to the public in source code form.  A
-"Major Component", in this context, means a major essential component
-(kernel, window system, and so on) of the specific operating system
-(if any) on which the executable work runs, or a compiler used to
-produce the work, or an object code interpreter used to run it.
-
-  The "Corresponding Source" for a work in object code form means all
-the source code needed to generate, install, and (for an executable
-work) run the object code and to modify the work, including scripts to
-control those activities.  However, it does not include the work's
-System Libraries, or general-purpose tools or generally available free
-programs which are used unmodified in performing those activities but
-which are not part of the work.  For example, Corresponding Source
-includes interface definition files associated with source files for
-the work, and the source code for shared libraries and dynamically
-linked subprograms that the work is specifically designed to require,
-such as by intimate data communication or control flow between those
-subprograms and other parts of the work.
-
-  The Corresponding Source need not include anything that users
-can regenerate automatically from other parts of the Corresponding
-Source.
-
-  The Corresponding Source for a work in source code form is that
-same work.
-
-  2. Basic Permissions.
-
-  All rights granted under this License are granted for the term of
-copyright on the Program, and are irrevocable provided the stated
-conditions are met.  This License explicitly affirms your unlimited
-permission to run the unmodified Program.  The output from running a
-covered work is covered by this License only if the output, given its
-content, constitutes a covered work.  This License acknowledges your
-rights of fair use or other equivalent, as provided by copyright law.
-
-  You may make, run and propagate covered works that you do not
-convey, without conditions so long as your license otherwise remains
-in force.  You may convey covered works to others for the sole purpose
-of having them make modifications exclusively for you, or provide you
-with facilities for running those works, provided that you comply with
-the terms of this License in conveying all material for which you do
-not control copyright.  Those thus making or running the covered works
-for you must do so exclusively on your behalf, under your direction
-and control, on terms that prohibit them from making any copies of
-your copyrighted material outside their relationship with you.
-
-  Conveying under any other circumstances is permitted solely under
-the conditions stated below.  Sublicensing is not allowed; section 10
-makes it unnecessary.
-
-  3. Protecting Users' Legal Rights From Anti-Circumvention Law.
-
-  No covered work shall be deemed part of an effective technological
-measure under any applicable law fulfilling obligations under article
-11 of the WIPO copyright treaty adopted on 20 December 1996, or
-similar laws prohibiting or restricting circumvention of such
-measures.
-
-  When you convey a covered work, you waive any legal power to forbid
-circumvention of technological measures to the extent such circumvention
-is effected by exercising rights under this License with respect to
-the covered work, and you disclaim any intention to limit operation or
-modification of the work as a means of enforcing, against the work's
-users, your or third parties' legal rights to forbid circumvention of
-technological measures.
-
-  4. Conveying Verbatim Copies.
-
-  You may convey verbatim copies of the Program's source code as you
-receive it, in any medium, provided that you conspicuously and
-appropriately publish on each copy an appropriate copyright notice;
-keep intact all notices stating that this License and any
-non-permissive terms added in accord with section 7 apply to the code;
-keep intact all notices of the absence of any warranty; and give all
-recipients a copy of this License along with the Program.
-
-  You may charge any price or no price for each copy that you convey,
-and you may offer support or warranty protection for a fee.
-
-  5. Conveying Modified Source Versions.
-
-  You may convey a work based on the Program, or the modifications to
-produce it from the Program, in the form of source code under the
-terms of section 4, provided that you also meet all of these conditions:
-
-    a) The work must carry prominent notices stating that you modified
-    it, and giving a relevant date.
-
-    b) The work must carry prominent notices stating that it is
-    released under this License and any conditions added under section
-    7.  This requirement modifies the requirement in section 4 to
-    "keep intact all notices".
-
-    c) You must license the entire work, as a whole, under this
-    License to anyone who comes into possession of a copy.  This
-    License will therefore apply, along with any applicable section 7
-    additional terms, to the whole of the work, and all its parts,
-    regardless of how they are packaged.  This License gives no
-    permission to license the work in any other way, but it does not
-    invalidate such permission if you have separately received it.
-
-    d) If the work has interactive user interfaces, each must display
-    Appropriate Legal Notices; however, if the Program has interactive
-    interfaces that do not display Appropriate Legal Notices, your
-    work need not make them do so.
-
-  A compilation of a covered work with other separate and independent
-works, which are not by their nature extensions of the covered work,
-and which are not combined with it such as to form a larger program,
-in or on a volume of a storage or distribution medium, is called an
-"aggregate" if the compilation and its resulting copyright are not
-used to limit the access or legal rights of the compilation's users
-beyond what the individual works permit.  Inclusion of a covered work
-in an aggregate does not cause this License to apply to the other
-parts of the aggregate.
-
-  6. Conveying Non-Source Forms.
-
-  You may convey a covered work in object code form under the terms
-of sections 4 and 5, provided that you also convey the
-machine-readable Corresponding Source under the terms of this License,
-in one of these ways:
-
-    a) Convey the object code in, or embodied in, a physical product
-    (including a physical distribution medium), accompanied by the
-    Corresponding Source fixed on a durable physical medium
-    customarily used for software interchange.
-
-    b) Convey the object code in, or embodied in, a physical product
-    (including a physical distribution medium), accompanied by a
-    written offer, valid for at least three years and valid for as
-    long as you offer spare parts or customer support for that product
-    model, to give anyone who possesses the object code either (1) a
-    copy of the Corresponding Source for all the software in the
-    product that is covered by this License, on a durable physical
-    medium customarily used for software interchange, for a price no
-    more than your reasonable cost of physically performing this
-    conveying of source, or (2) access to copy the
-    Corresponding Source from a network server at no charge.
-
-    c) Convey individual copies of the object code with a copy of the
-    written offer to provide the Corresponding Source.  This
-    alternative is allowed only occasionally and noncommercially, and
-    only if you received the object code with such an offer, in accord
-    with subsection 6b.
-
-    d) Convey the object code by offering access from a designated
-    place (gratis or for a charge), and offer equivalent access to the
-    Corresponding Source in the same way through the same place at no
-    further charge.  You need not require recipients to copy the
-    Corresponding Source along with the object code.  If the place to
-    copy the object code is a network server, the Corresponding Source
-    may be on a different server (operated by you or a third party)
-    that supports equivalent copying facilities, provided you maintain
-    clear directions next to the object code saying where to find the
-    Corresponding Source.  Regardless of what server hosts the
-    Corresponding Source, you remain obligated to ensure that it is
-    available for as long as needed to satisfy these requirements.
-
-    e) Convey the object code using peer-to-peer transmission, provided
-    you inform other peers where the object code and Corresponding
-    Source of the work are being offered to the general public at no
-    charge under subsection 6d.
-
-  A separable portion of the object code, whose source code is excluded
-from the Corresponding Source as a System Library, need not be
-included in conveying the object code work.
-
-  A "User Product" is either (1) a "consumer product", which means any
-tangible personal property which is normally used for personal, family,
-or household purposes, or (2) anything designed or sold for incorporation
-into a dwelling.  In determining whether a product is a consumer product,
-doubtful cases shall be resolved in favor of coverage.  For a particular
-product received by a particular user, "normally used" refers to a
-typical or common use of that class of product, regardless of the status
-of the particular user or of the way in which the particular user
-actually uses, or expects or is expected to use, the product.  A product
-is a consumer product regardless of whether the product has substantial
-commercial, industrial or non-consumer uses, unless such uses represent
-the only significant mode of use of the product.
-
-  "Installation Information" for a User Product means any methods,
-procedures, authorization keys, or other information required to install
-and execute modified versions of a covered work in that User Product from
-a modified version of its Corresponding Source.  The information must
-suffice to ensure that the continued functioning of the modified object
-code is in no case prevented or interfered with solely because
-modification has been made.
-
-  If you convey an object code work under this section in, or with, or
-specifically for use in, a User Product, and the conveying occurs as
-part of a transaction in which the right of possession and use of the
-User Product is transferred to the recipient in perpetuity or for a
-fixed term (regardless of how the transaction is characterized), the
-Corresponding Source conveyed under this section must be accompanied
-by the Installation Information.  But this requirement does not apply
-if neither you nor any third party retains the ability to install
-modified object code on the User Product (for example, the work has
-been installed in ROM).
-
-  The requirement to provide Installation Information does not include a
-requirement to continue to provide support service, warranty, or updates
-for a work that has been modified or installed by the recipient, or for
-the User Product in which it has been modified or installed.  Access to a
-network may be denied when the modification itself materially and
-adversely affects the operation of the network or violates the rules and
-protocols for communication across the network.
-
-  Corresponding Source conveyed, and Installation Information provided,
-in accord with this section must be in a format that is publicly
-documented (and with an implementation available to the public in
-source code form), and must require no special password or key for
-unpacking, reading or copying.
-
-  7. Additional Terms.
-
-  "Additional permissions" are terms that supplement the terms of this
-License by making exceptions from one or more of its conditions.
-Additional permissions that are applicable to the entire Program shall
-be treated as though they were included in this License, to the extent
-that they are valid under applicable law.  If additional permissions
-apply only to part of the Program, that part may be used separately
-under those permissions, but the entire Program remains governed by
-this License without regard to the additional permissions.
-
-  When you convey a copy of a covered work, you may at your option
-remove any additional permissions from that copy, or from any part of
-it.  (Additional permissions may be written to require their own
-removal in certain cases when you modify the work.)  You may place
-additional permissions on material, added by you to a covered work,
-for which you have or can give appropriate copyright permission.
-
-  Notwithstanding any other provision of this License, for material you
-add to a covered work, you may (if authorized by the copyright holders of
-that material) supplement the terms of this License with terms:
-
-    a) Disclaiming warranty or limiting liability differently from the
-    terms of sections 15 and 16 of this License; or
-
-    b) Requiring preservation of specified reasonable legal notices or
-    author attributions in that material or in the Appropriate Legal
-    Notices displayed by works containing it; or
-
-    c) Prohibiting misrepresentation of the origin of that material, or
-    requiring that modified versions of such material be marked in
-    reasonable ways as different from the original version; or
-
-    d) Limiting the use for publicity purposes of names of licensors or
-    authors of the material; or
-
-    e) Declining to grant rights under trademark law for use of some
-    trade names, trademarks, or service marks; or
-
-    f) Requiring indemnification of licensors and authors of that
-    material by anyone who conveys the material (or modified versions of
-    it) with contractual assumptions of liability to the recipient, for
-    any liability that these contractual assumptions directly impose on
-    those licensors and authors.
-
-  All other non-permissive additional terms are considered "further
-restrictions" within the meaning of section 10.  If the Program as you
-received it, or any part of it, contains a notice stating that it is
-governed by this License along with a term that is a further
-restriction, you may remove that term.  If a license document contains
-a further restriction but permits relicensing or conveying under this
-License, you may add to a covered work material governed by the terms
-of that license document, provided that the further restriction does
-not survive such relicensing or conveying.
-
-  If you add terms to a covered work in accord with this section, you
-must place, in the relevant source files, a statement of the
-additional terms that apply to those files, or a notice indicating
-where to find the applicable terms.
-
-  Additional terms, permissive or non-permissive, may be stated in the
-form of a separately written license, or stated as exceptions;
-the above requirements apply either way.
-
-  8. Termination.
-
-  You may not propagate or modify a covered work except as expressly
-provided under this License.  Any attempt otherwise to propagate or
-modify it is void, and will automatically terminate your rights under
-this License (including any patent licenses granted under the third
-paragraph of section 11).
-
-  However, if you cease all violation of this License, then your
-license from a particular copyright holder is reinstated (a)
-provisionally, unless and until the copyright holder explicitly and
-finally terminates your license, and (b) permanently, if the copyright
-holder fails to notify you of the violation by some reasonable means
-prior to 60 days after the cessation.
-
-  Moreover, your license from a particular copyright holder is
-reinstated permanently if the copyright holder notifies you of the
-violation by some reasonable means, this is the first time you have
-received notice of violation of this License (for any work) from that
-copyright holder, and you cure the violation prior to 30 days after
-your receipt of the notice.
-
-  Termination of your rights under this section does not terminate the
-licenses of parties who have received copies or rights from you under
-this License.  If your rights have been terminated and not permanently
-reinstated, you do not qualify to receive new licenses for the same
-material under section 10.
-
-  9. Acceptance Not Required for Having Copies.
-
-  You are not required to accept this License in order to receive or
-run a copy of the Program.  Ancillary propagation of a covered work
-occurring solely as a consequence of using peer-to-peer transmission
-to receive a copy likewise does not require acceptance.  However,
-nothing other than this License grants you permission to propagate or
-modify any covered work.  These actions infringe copyright if you do
-not accept this License.  Therefore, by modifying or propagating a
-covered work, you indicate your acceptance of this License to do so.
-
-  10. Automatic Licensing of Downstream Recipients.
-
-  Each time you convey a covered work, the recipient automatically
-receives a license from the original licensors, to run, modify and
-propagate that work, subject to this License.  You are not responsible
-for enforcing compliance by third parties with this License.
-
-  An "entity transaction" is a transaction transferring control of an
-organization, or substantially all assets of one, or subdividing an
-organization, or merging organizations.  If propagation of a covered
-work results from an entity transaction, each party to that
-transaction who receives a copy of the work also receives whatever
-licenses to the work the party's predecessor in interest had or could
-give under the previous paragraph, plus a right to possession of the
-Corresponding Source of the work from the predecessor in interest, if
-the predecessor has it or can get it with reasonable efforts.
-
-  You may not impose any further restrictions on the exercise of the
-rights granted or affirmed under this License.  For example, you may
-not impose a license fee, royalty, or other charge for exercise of
-rights granted under this License, and you may not initiate litigation
-(including a cross-claim or counterclaim in a lawsuit) alleging that
-any patent claim is infringed by making, using, selling, offering for
-sale, or importing the Program or any portion of it.
-
-  11. Patents.
-
-  A "contributor" is a copyright holder who authorizes use under this
-License of the Program or a work on which the Program is based.  The
-work thus licensed is called the contributor's "contributor version".
-
-  A contributor's "essential patent claims" are all patent claims
-owned or controlled by the contributor, whether already acquired or
-hereafter acquired, that would be infringed by some manner, permitted
-by this License, of making, using, or selling its contributor version,
-but do not include claims that would be infringed only as a
-consequence of further modification of the contributor version.  For
-purposes of this definition, "control" includes the right to grant
-patent sublicenses in a manner consistent with the requirements of
-this License.
-
-  Each contributor grants you a non-exclusive, worldwide, royalty-free
-patent license under the contributor's essential patent claims, to
-make, use, sell, offer for sale, import and otherwise run, modify and
-propagate the contents of its contributor version.
-
-  In the following three paragraphs, a "patent license" is any express
-agreement or commitment, however denominated, not to enforce a patent
-(such as an express permission to practice a patent or covenant not to
-sue for patent infringement).  To "grant" such a patent license to a
-party means to make such an agreement or commitment not to enforce a
-patent against the party.
-
-  If you convey a covered work, knowingly relying on a patent license,
-and the Corresponding Source of the work is not available for anyone
-to copy, free of charge and under the terms of this License, through a
-publicly available network server or other readily accessible means,
-then you must either (1) cause the Corresponding Source to be so
-available, or (2) arrange to deprive yourself of the benefit of the
-patent license for this particular work, or (3) arrange, in a manner
-consistent with the requirements of this License, to extend the patent
-license to downstream recipients.  "Knowingly relying" means you have
-actual knowledge that, but for the patent license, your conveying the
-covered work in a country, or your recipient's use of the covered work
-in a country, would infringe one or more identifiable patents in that
-country that you have reason to believe are valid.
-
-  If, pursuant to or in connection with a single transaction or
-arrangement, you convey, or propagate by procuring conveyance of, a
-covered work, and grant a patent license to some of the parties
-receiving the covered work authorizing them to use, propagate, modify
-or convey a specific copy of the covered work, then the patent license
-you grant is automatically extended to all recipients of the covered
-work and works based on it.
-
-  A patent license is "discriminatory" if it does not include within
-the scope of its coverage, prohibits the exercise of, or is
-conditioned on the non-exercise of one or more of the rights that are
-specifically granted under this License.  You may not convey a covered
-work if you are a party to an arrangement with a third party that is
-in the business of distributing software, under which you make payment
-to the third party based on the extent of your activity of conveying
-the work, and under which the third party grants, to any of the
-parties who would receive the covered work from you, a discriminatory
-patent license (a) in connection with copies of the covered work
-conveyed by you (or copies made from those copies), or (b) primarily
-for and in connection with specific products or compilations that
-contain the covered work, unless you entered into that arrangement,
-or that patent license was granted, prior to 28 March 2007.
-
-  Nothing in this License shall be construed as excluding or limiting
-any implied license or other defenses to infringement that may
-otherwise be available to you under applicable patent law.
-
-  12. No Surrender of Others' Freedom.
-
-  If conditions are imposed on you (whether by court order, agreement or
-otherwise) that contradict the conditions of this License, they do not
-excuse you from the conditions of this License.  If you cannot convey a
-covered work so as to satisfy simultaneously your obligations under this
-License and any other pertinent obligations, then as a consequence you may
-not convey it at all.  For example, if you agree to terms that obligate you
-to collect a royalty for further conveying from those to whom you convey
-the Program, the only way you could satisfy both those terms and this
-License would be to refrain entirely from conveying the Program.
-
-  13. Use with the GNU Affero General Public License.
-
-  Notwithstanding any other provision of this License, you have
-permission to link or combine any covered work with a work licensed
-under version 3 of the GNU Affero General Public License into a single
-combined work, and to convey the resulting work.  The terms of this
-License will continue to apply to the part which is the covered work,
-but the special requirements of the GNU Affero General Public License,
-section 13, concerning interaction through a network will apply to the
-combination as such.
-
-  14. Revised Versions of this License.
-
-  The Free Software Foundation may publish revised and/or new versions of
-the GNU General Public License from time to time.  Such new versions will
-be similar in spirit to the present version, but may differ in detail to
-address new problems or concerns.
-
-  Each version is given a distinguishing version number.  If the
-Program specifies that a certain numbered version of the GNU General
-Public License "or any later version" applies to it, you have the
-option of following the terms and conditions either of that numbered
-version or of any later version published by the Free Software
-Foundation.  If the Program does not specify a version number of the
-GNU General Public License, you may choose any version ever published
-by the Free Software Foundation.
-
-  If the Program specifies that a proxy can decide which future
-versions of the GNU General Public License can be used, that proxy's
-public statement of acceptance of a version permanently authorizes you
-to choose that version for the Program.
-
-  Later license versions may give you additional or different
-permissions.  However, no additional obligations are imposed on any
-author or copyright holder as a result of your choosing to follow a
-later version.
-
-  15. Disclaimer of Warranty.
-
-  THERE IS NO WARRANTY FOR THE PROGRAM, TO THE EXTENT PERMITTED BY
-APPLICABLE LAW.  EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT
-HOLDERS AND/OR OTHER PARTIES PROVIDE THE PROGRAM "AS IS" WITHOUT WARRANTY
-OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO,
-THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
-PURPOSE.  THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE PROGRAM
-IS WITH YOU.  SHOULD THE PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF
-ALL NECESSARY SERVICING, REPAIR OR CORRECTION.
-
-  16. Limitation of Liability.
-
-  IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING
-WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MODIFIES AND/OR CONVEYS
-THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES, INCLUDING ANY
-GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE
-USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED TO LOSS OF
-DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD
-PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER PROGRAMS),
-EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF
-SUCH DAMAGES.
-
-  17. Interpretation of Sections 15 and 16.
-
-  If the disclaimer of warranty and limitation of liability provided
-above cannot be given local legal effect according to their terms,
-reviewing courts shall apply local law that most closely approximates
-an absolute waiver of all civil liability in connection with the
-Program, unless a warranty or assumption of liability accompanies a
-copy of the Program in return for a fee.
-
-                     END OF TERMS AND CONDITIONS
-
-            How to Apply These Terms to Your New Programs
-
-  If you develop a new program, and you want it to be of the greatest
-possible use to the public, the best way to achieve this is to make it
-free software which everyone can redistribute and change under these terms.
-
-  To do so, attach the following notices to the program.  It is safest
-to attach them to the start of each source file to most effectively
-state the exclusion of warranty; and each file should have at least
-the "copyright" line and a pointer to where the full notice is found.
-
-    <one line to give the program's name and a brief idea of what it does.>
-    Copyright (C) <year>  <name of author>
-
-    This program is free software: you can redistribute it and/or modify
-    it under the terms of the GNU General Public License as published by
-    the Free Software Foundation, either version 3 of the License, or
-    (at your option) any later version.
-
-    This program is distributed in the hope that it will be useful,
-    but WITHOUT ANY WARRANTY; without even the implied warranty of
-    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
-    GNU General Public License for more details.
-
-    You should have received a copy of the GNU General Public License
-    along with this program.  If not, see <http://www.gnu.org/licenses/>.
-
-Also add information on how to contact you by electronic and paper mail.
-
-  If the program does terminal interaction, make it output a short
-notice like this when it starts in an interactive mode:
-
-    <program>  Copyright (C) <year>  <name of author>
-    This program comes with ABSOLUTELY NO WARRANTY; for details type `show w'.
-    This is free software, and you are welcome to redistribute it
-    under certain conditions; type `show c' for details.
-
-The hypothetical commands `show w' and `show c' should show the appropriate
-parts of the General Public License.  Of course, your program's commands
-might be different; for a GUI interface, you would use an "about box".
-
-  You should also get your employer (if you work as a programmer) or school,
-if any, to sign a "copyright disclaimer" for the program, if necessary.
-For more information on this, and how to apply and follow the GNU GPL, see
-<http://www.gnu.org/licenses/>.
-
-  The GNU General Public License does not permit incorporating your program
-into proprietary programs.  If your program is a subroutine library, you
-may consider it more useful to permit linking proprietary applications with
-the library.  If this is what you want to do, use the GNU Lesser General
-Public License instead of this License.  But first, please read
-<http://www.gnu.org/philosophy/why-not-lgpl.html>.

COPYING.LESSER

@@ -1,165 +0,0 @@
-                   GNU LESSER GENERAL PUBLIC LICENSE
-                       Version 3, 29 June 2007
-
- Copyright (C) 2007 Free Software Foundation, Inc. <http://fsf.org/>
- Everyone is permitted to copy and distribute verbatim copies
- of this license document, but changing it is not allowed.
-
-
-  This version of the GNU Lesser General Public License incorporates
-the terms and conditions of version 3 of the GNU General Public
-License, supplemented by the additional permissions listed below.
-
-  0. Additional Definitions.
-
-  As used herein, "this License" refers to version 3 of the GNU Lesser
-General Public License, and the "GNU GPL" refers to version 3 of the GNU
-General Public License.
-
-  "The Library" refers to a covered work governed by this License,
-other than an Application or a Combined Work as defined below.
-
-  An "Application" is any work that makes use of an interface provided
-by the Library, but which is not otherwise based on the Library.
-Defining a subclass of a class defined by the Library is deemed a mode
-of using an interface provided by the Library.
-
-  A "Combined Work" is a work produced by combining or linking an
-Application with the Library.  The particular version of the Library
-with which the Combined Work was made is also called the "Linked
-Version".
-
-  The "Minimal Corresponding Source" for a Combined Work means the
-Corresponding Source for the Combined Work, excluding any source code
-for portions of the Combined Work that, considered in isolation, are
-based on the Application, and not on the Linked Version.
-
-  The "Corresponding Application Code" for a Combined Work means the
-object code and/or source code for the Application, including any data
-and utility programs needed for reproducing the Combined Work from the
-Application, but excluding the System Libraries of the Combined Work.
-
-  1. Exception to Section 3 of the GNU GPL.
-
-  You may convey a covered work under sections 3 and 4 of this License
-without being bound by section 3 of the GNU GPL.
-
-  2. Conveying Modified Versions.
-
-  If you modify a copy of the Library, and, in your modifications, a
-facility refers to a function or data to be supplied by an Application
-that uses the facility (other than as an argument passed when the
-facility is invoked), then you may convey a copy of the modified
-version:
-
-   a) under this License, provided that you make a good faith effort to
-   ensure that, in the event an Application does not supply the
-   function or data, the facility still operates, and performs
-   whatever part of its purpose remains meaningful, or
-
-   b) under the GNU GPL, with none of the additional permissions of
-   this License applicable to that copy.
-
-  3. Object Code Incorporating Material from Library Header Files.
-
-  The object code form of an Application may incorporate material from
-a header file that is part of the Library.  You may convey such object
-code under terms of your choice, provided that, if the incorporated
-material is not limited to numerical parameters, data structure
-layouts and accessors, or small macros, inline functions and templates
-(ten or fewer lines in length), you do both of the following:
-
-   a) Give prominent notice with each copy of the object code that the
-   Library is used in it and that the Library and its use are
-   covered by this License.
-
-   b) Accompany the object code with a copy of the GNU GPL and this license
-   document.
-
-  4. Combined Works.
-
-  You may convey a Combined Work under terms of your choice that,
-taken together, effectively do not restrict modification of the
-portions of the Library contained in the Combined Work and reverse
-engineering for debugging such modifications, if you also do each of
-the following:
-
-   a) Give prominent notice with each copy of the Combined Work that
-   the Library is used in it and that the Library and its use are
-   covered by this License.
-
-   b) Accompany the Combined Work with a copy of the GNU GPL and this license
-   document.
-
-   c) For a Combined Work that displays copyright notices during
-   execution, include the copyright notice for the Library among
-   these notices, as well as a reference directing the user to the
-   copies of the GNU GPL and this license document.
-
-   d) Do one of the following:
-
-       0) Convey the Minimal Corresponding Source under the terms of this
-       License, and the Corresponding Application Code in a form
-       suitable for, and under terms that permit, the user to
-       recombine or relink the Application with a modified version of
-       the Linked Version to produce a modified Combined Work, in the
-       manner specified by section 6 of the GNU GPL for conveying
-       Corresponding Source.
-
-       1) Use a suitable shared library mechanism for linking with the
-       Library.  A suitable mechanism is one that (a) uses at run time
-       a copy of the Library already present on the user's computer
-       system, and (b) will operate properly with a modified version
-       of the Library that is interface-compatible with the Linked
-       Version.
-
-   e) Provide Installation Information, but only if you would otherwise
-   be required to provide such information under section 6 of the
-   GNU GPL, and only to the extent that such information is
-   necessary to install and execute a modified version of the
-   Combined Work produced by recombining or relinking the
-   Application with a modified version of the Linked Version. (If
-   you use option 4d0, the Installation Information must accompany
-   the Minimal Corresponding Source and Corresponding Application
-   Code. If you use option 4d1, you must provide the Installation
-   Information in the manner specified by section 6 of the GNU GPL
-   for conveying Corresponding Source.)
-
-  5. Combined Libraries.
-
-  You may place library facilities that are a work based on the
-Library side by side in a single library together with other library
-facilities that are not Applications and are not covered by this
-License, and convey such a combined library under terms of your
-choice, if you do both of the following:
-
-   a) Accompany the combined library with a copy of the same work based
-   on the Library, uncombined with any other library facilities,
-   conveyed under the terms of this License.
-
-   b) Give prominent notice with the combined library that part of it
-   is a work based on the Library, and explaining where to find the
-   accompanying uncombined form of the same work.
-
-  6. Revised Versions of the GNU Lesser General Public License.
-
-  The Free Software Foundation may publish revised and/or new versions
-of the GNU Lesser General Public License from time to time. Such new
-versions will be similar in spirit to the present version, but may
-differ in detail to address new problems or concerns.
-
-  Each version is given a distinguishing version number. If the
-Library as you received it specifies that a certain numbered version
-of the GNU Lesser General Public License "or any later version"
-applies to it, you have the option of following the terms and
-conditions either of that published version or of any later version
-published by the Free Software Foundation. If the Library as you
-received it does not specify a version number of the GNU Lesser
-General Public License, you may choose any version of the GNU Lesser
-General Public License ever published by the Free Software Foundation.
-
-  If the Library as you received it specifies that a proxy can decide
-whether future versions of the GNU Lesser General Public License shall
-apply, that proxy's public statement of acceptance of any version is
-permanent authorization for you to choose that version for the
-Library.

HISTORY.rst

@@ -0,0 +1,272 @@
+Changelog
+---------
+
+2.0.3
+^^^^^
+**release date:** 2016-06-10
+
+* Fix clearing cache in CLI
+
+
+2.0.2
+^^^^^
+**release date:** 2016-06-06
+
+* Fix for dogpile.cache>=0.6.0
+* Fix missing sphinx_rtd_theme dependency
+
+
+2.0.1
+^^^^^
+**release date:** 2016-06-06
+
+* Fix beautifulsoup4 minimal requirement
+
+
+2.0.0
+^^^^^
+**release date:** 2016-06-04
+
+* Add refiners to enrich videos with information from metadata, tvdb and omdb
+* Add asynchronous provider search for faster searches
+* Add registrable managers so subliminal can run without install
+* Add archive support
+* Add the ability to customize scoring logic
+* Add an age argument to scan_videos for faster scanning
+* Add legendas.tv provider
+* Add shooter.cn provider
+* Improve matching and scoring
+* Improve documentation
+* Split nautilus integration into its own project
+
+
+1.1.1
+^^^^^
+**release date:** 2016-01-03
+
+* Fix scanning videos on bad MKV files
+
+
+1.1
+^^^
+**release date:** 2015-12-29
+
+* Fix library usage example in README
+* Fix for series name with special characters in addic7ed provider
+* Fix id property in thesubdb provider
+* Improve matching on titles
+* Add support for nautilus context menu with translations
+* Add support for searching subtitles in a separate directory
+* Add subscenter provider
+* Add support for python 3.5
+
+
+1.0.1
+^^^^^
+**release date:** 2015-07-23
+
+* Fix unicode issues in CLI (python 2 only)
+* Fix score scaling in CLI (python 2 only)
+* Improve error handling in CLI
+* Color collect report in CLI
+
+
+1.0
+^^^
+**release date:** 2015-07-22
+
+* Many changes and fixes
+* New test suite
+* New documentation
+* New CLI
+* Added support for SubsCenter
+
+
+0.7.5
+^^^^^
+**release date:** 2015-03-04
+
+* Update requirements
+* Remove BierDopje provider
+* Add pre-guessed video optional argument in scan_video
+* Improve hearing impaired support
+* Fix TVSubtitles and Podnapisi providers
+
+
+0.7.4
+^^^^^
+**release date:** 2014-01-27
+
+* Fix requirements for guessit and babelfish
+
+
+0.7.3
+^^^^^
+**release date:** 2013-11-22
+
+* Fix windows compatibility
+* Improve subtitle validation
+* Improve embedded subtitle languages detection
+* Improve unittests
+
+
+0.7.2
+^^^^^
+**release date:** 2013-11-10
+
+* Fix TVSubtitles for ambiguous series
+* Add a CACHE_VERSION to force cache reloading on version change
+* Set CLI default cache expiration time to 30 days
+* Add podnapisi provider
+* Support script for languages e.g. Latn, Cyrl
+* Improve logging levels
+* Fix subtitle validation in some rare cases
+
+
+0.7.1
+^^^^^
+**release date:** 2013-11-06
+
+* Improve CLI
+* Add login support for Addic7ed
+* Remove lxml dependency
+* Many fixes
+
+
+0.7.0
+^^^^^
+**release date:** 2013-10-29
+
+**WARNING:** Complete rewrite of subliminal with backward incompatible changes
+
+* Use enzyme to parse metadata of videos
+* Use babelfish to handle languages
+* Use dogpile.cache for caching
+* Use charade to detect subtitle encoding
+* Use pysrt for subtitle validation
+* Use entry points for subtitle providers
+* New subtitle score computation
+* Hearing impaired subtitles support
+* Drop async support
+* Drop a few providers
+* And much more...
+
+
+0.6.4
+^^^^^
+**release date:** 2013-05-19
+
+* Fix requirements due to enzyme 0.3
+
+
+0.6.3
+^^^^^
+**release date:** 2013-01-17
+
+* Fix requirements due to requests 1.0
+
+
+0.6.2
+^^^^^
+**release date:** 2012-09-15
+
+* Fix BierDopje
+* Fix Addic7ed
+* Fix SubsWiki
+* Fix missing enzyme import
+* Add Catalan and Galician languages to Addic7ed
+* Add possible services in help message of the CLI
+* Allow existing filenames to be passed without the ./ prefix
+
+
+0.6.1
+^^^^^
+**release date:** 2012-06-24
+
+* Fix subtitle release name in BierDopje
+* Fix subtitles being downloaded multiple times
+* Add Chinese support to TvSubtitles
+* Fix encoding issues
+* Fix single download subtitles without the force option
+* Add Spanish (Latin America) exception to Addic7ed
+* Fix group_by_video when a list entry has None as subtitles
+* Add support for Galician language in Subtitulos
+* Add an integrity check after subtitles download for Addic7ed
+* Add error handling for if not strict in Language
+* Fix TheSubDB hash method to return None if the file is too small
+* Fix guessit.Language in Video.scan
+* Fix language detection of subtitles
+
+
+0.6.0
+^^^^^
+**release date:** 2012-06-16
+
+**WARNING:** Backward incompatible changes
+
+* Fix --workers option in CLI
+* Use a dedicated module for languages
+* Use beautifulsoup4
+* Improve return types
+* Add scan_filter option
+* Add --age option in CLI
+* Add TvSubtitles service
+* Add Addic7ed service
+
+
+0.5.1
+^^^^^
+**release date:** 2012-03-25
+
+* Improve error handling of enzyme parsing
+
+
+0.5
+^^^
+**release date:** 2012-03-25
+**WARNING:** Backward incompatible changes
+
+* Use more unicode
+* New list_subtitles and download_subtitles methods
+* New Pool object for asynchronous work
+* Improve sort algorithm
+* Better error handling
+* Make sorting customizable
+* Remove class Subliminal
+* Remove permissions handling
+
+
+0.4
+^^^
+**release date:** 2011-11-11
+
+* Many fixes
+* Better error handling
+
+
+0.3
+^^^
+**release date:** 2011-08-18
+
+* Fix a bug when series is not guessed by guessit
+* Fix dependencies failure when installing package
+* Fix encoding issues with logging
+* Add a script to ease subtitles download
+* Add possibility to choose mode of created files
+* Add more checks before adjusting permissions
+
+
+0.2
+^^^
+**release date:** 2011-07-11
+
+* Fix plugin configuration
+* Fix some encoding issues
+* Remove extra logging
+
+
+0.1
+^^^
+**release date:** *private release*
+
+* Initial release

LICENSE

@@ -0,0 +1,20 @@
+The MIT License (MIT)
+
+Copyright (c) 2016 Antoine Bertin
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of
+this software and associated documentation files (the "Software"), to deal in
+the Software without restriction, including without limitation the rights to
+use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of
+the Software, and to permit persons to whom the Software is furnished to do so,
+subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
+FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
+COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
+IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
+CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

MANIFEST.in

@@ -1 +1 @@
-include COPYING COPYING.LESSER NEWS.rst README.rst
+include LICENSE HISTORY.rst requirements.txt

NEWS.rst

@@ -1,87 +0,0 @@
-News
-====
-
-0.6.1
------
-**release date:** 2012-06-24
-
-* Fix subtitle release name in BierDopje
-* Fix subtitles being downloaded multiple times
-* Add Chinese support to TvSubtitles
-* Fix encoding issues
-* Fix single download subtitles without the force option
-* Add Spanish (Latin America) exception to Addic7ed
-* Fix group_by_video when a list entry has None as subtitles
-* Add support for Galician language in Subtitulos
-* Add an integrity check after subtitles download for Addic7ed
-* Add error handling for if not strict in Language
-* Fix TheSubDB hash method to return None if the file is too small
-* Fix guessit.Language in Video.scan
-* Fix language detection of subtitles
-
-0.6.0
------
-**release date:** 2012-06-16
-**WARNING:** Backward incompatible changes
-
-* Fix --workers option in CLI
-* Use a dedicated module for languages
-* Use beautifulsoup4
-* Improve return types
-* Add scan_filter option
-* Add --age option in CLI
-* Add TvSubtitles service
-* Add Addic7ed service
-
-
-0.5.1
------
-**release date:** 2012-03-25
-
-* Improve error handling of enzyme parsing
-
-0.5
----
-**release date:** 2012-03-25
-**WARNING:** Backward incompatible changes
-
-* Use more unicode
-* New list_subtitles and download_subtitles methods
-* New Pool object for asynchronous work
-* Improve sort algorithm
-* Better error handling
-* Make sorting customizable
-* Remove class Subliminal
-* Remove permissions handling
-
-0.4
----
-**release date:** 2011-11-11
-
-* Many fixes
-* Better error handling
-
-0.3
----
-**release date:** 2011-08-18
-
-* Fix a bug when series is not guessed by guessit
-* Fix dependencies failure when installing package
-* Fix encoding issues with logging
-* Add a script to ease subtitles download
-* Add possibility to choose mode of created files
-* Add more checks before adjusting permissions
-
-0.2
----
-**release date:** 2011-07-11
-
-* Fix plugin configuration
-* Fix some encoding issues
-* Remove extra logging
-
-0.1
----
-**release date:** not released yet
-
-* Initial release

README.rst

@@ -1,48 +1,82 @@
 Subliminal
 ==========
+Subtitles, faster than your thoughts.
 
-.. image:: https://secure.travis-ci.org/Diaoul/subliminal.png?branch=develop
+.. image:: https://img.shields.io/pypi/v/subliminal.svg
+    :target: https://pypi.python.org/pypi/subliminal
+    :alt: Latest Version
 
-Subliminal is a python library to search and download subtitles.
+.. image:: https://travis-ci.org/Diaoul/subliminal.svg?branch=develop
+   :target: https://travis-ci.org/Diaoul/subliminal
+   :alt: Travis CI build status
 
-It uses video hashes and the powerful `guessit <http://guessit.readthedocs.org/>`_ library
-that extracts informations from filenames or filepaths to ensure you have the best subtitles.
-It also relies on `enzyme <https://github.com/Diaoul/enzyme>`_ to detect embedded subtitles
-and avoid duplicates.
+.. image:: https://readthedocs.org/projects/subliminal/badge/?version=latest
+   :target: https://subliminal.readthedocs.org/
+   :alt: Documentation Status
 
-Features
---------
-Multiple subtitles services are available:
+.. image:: https://coveralls.io/repos/Diaoul/subliminal/badge.svg?branch=develop&service=github
+   :target: https://coveralls.io/github/Diaoul/subliminal?branch=develop
+   :alt: Code coverage
 
-* Addic7ed
-* BierDopje
-* OpenSubtitles
-* SubsWiki
-* Subtitulos
-* TheSubDB
-* TvSubtitles
+.. image:: https://img.shields.io/github/license/Diaoul/subliminal.svg
+   :target: https://github.com/Diaoul/subliminal/blob/master/LICENSE
+   :alt: License
 
-You can use main subliminal's functions with a **file path**, a **file name** or a **folder path**.
+.. image:: https://img.shields.io/badge/gitter-join%20chat-1dce73.svg
+   :alt: Join the chat at https://gitter.im/Diaoul/subliminal
+   :target: https://gitter.im/Diaoul/subliminal
 
+
+:Project page: https://github.com/Diaoul/subliminal
+:Documentation: https://subliminal.readthedocs.org/
+
+
+Usage
+-----
 CLI
 ^^^
-Download english subtitles::
+Download English subtitles::
 
-    $ subliminal -l en The.Big.Bang.Theory.S05E18.HDTV.x264-LOL.mp4
-    **************************************************
-    Downloaded 1 subtitle(s) for 1 video(s)
-    The.Big.Bang.Theory.S05E18.HDTV.x264-LOL.srt from opensubtitles
-    **************************************************
+    $ subliminal download -l en The.Big.Bang.Theory.S05E18.HDTV.x264-LOL.mp4
+    Collecting videos  [####################################]  100%
+    1 video collected / 0 video ignored / 0 error
+    Downloading subtitles  [####################################]  100%
+    Downloaded 1 subtitle
 
-Module
-^^^^^^
-List english subtitles::
+Library
+^^^^^^^
+Download best subtitles in French and English for videos less than two weeks old in a video folder:
 
-    >>> subliminal.list_subtitles('The.Big.Bang.Theory.S05E18.HDTV.x264-LOL.mp4', ['en'])
+.. code:: python
 
-Multi-threaded use
-^^^^^^^^^^^^^^^^^^
-Use 4 workers to achieve the same result::
+    from datetime import timedelta
 
-    >>> with subliminal.Pool(4) as p:
-    ...     p.list_subtitles('The.Big.Bang.Theory.S05E18.HDTV.x264-LOL.mp4', ['en'])
+    from babelfish import Language
+    from subliminal import download_best_subtitles, region, save_subtitles, scan_videos
+
+    # configure the cache
+    region.configure('dogpile.cache.dbm', arguments={'filename': 'cachefile.dbm'})
+
+    # scan for videos newer than 2 weeks and their existing subtitles in a folder
+    videos = scan_videos('/video/folder', age=timedelta(weeks=2))
+
+    # download best subtitles
+    subtitles = download_best_subtitles(videos, {Language('eng'), Language('fra')})
+
+    # save them to disk, next to the video
+    for v in videos:
+        save_subtitles(v, subtitles[v])
+
+
+Installation
+------------
+Subliminal can be installed as a regular python module by running::
+
+   $ [sudo] pip install subliminal
+
+For a better isolation with your system you should use a dedicated virtualenv or install for your user only using
+the ``--user`` flag.
+
+Nautilus/Nemo integration
+-------------------------
+See the dedicated `project page <https://github.com/Diaoul/nautilus-subliminal>`_ for more information.

dev-requirements.txt

@@ -0,0 +1 @@
+-e .[dev,test]

docs/Makefile

@@ -2,11 +2,16 @@
 #
 
 # You can set these variables from the command line.
-SPHINXOPTS    =
+SPHINXOPTS    = -n -W
 SPHINXBUILD   = sphinx-build
 PAPER         =
 BUILDDIR      = _build
 
+# User-friendly check for sphinx-build
+ifeq ($(shell which $(SPHINXBUILD) >/dev/null 2>&1; echo $$?), 1)
+$(error The '$(SPHINXBUILD)' command was not found. Make sure you have Sphinx installed, then set the SPHINXBUILD environment variable to point to the full path of the '$(SPHINXBUILD)' executable. Alternatively you can add the directory with the executable to your PATH. If you don't have Sphinx installed, grab it from http://sphinx-doc.org/)
+endif
+
 # Internal variables.
 PAPEROPT_a4     = -D latex_paper_size=a4
 PAPEROPT_letter = -D latex_paper_size=letter
@@ -14,7 +19,7 @@ ALLSPHINXOPTS   = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) .
 # the i18n builder cannot share the environment and doctrees with the others
 I18NSPHINXOPTS  = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) .
 
-.PHONY: help clean html dirhtml singlehtml pickle json htmlhelp qthelp devhelp epub latex latexpdf text man changes linkcheck doctest gettext
+.PHONY: help clean html dirhtml singlehtml pickle json htmlhelp qthelp devhelp epub latex latexpdf text man changes linkcheck doctest coverage gettext
 
 help:
 	@echo "Please use \`make <target>' where <target> is one of"
@@ -25,21 +30,26 @@ help:
 	@echo "  json       to make JSON files"
 	@echo "  htmlhelp   to make HTML files and a HTML help project"
 	@echo "  qthelp     to make HTML files and a qthelp project"
+	@echo "  applehelp  to make an Apple Help Book"
 	@echo "  devhelp    to make HTML files and a Devhelp project"
 	@echo "  epub       to make an epub"
 	@echo "  latex      to make LaTeX files, you can set PAPER=a4 or PAPER=letter"
 	@echo "  latexpdf   to make LaTeX files and run them through pdflatex"
+	@echo "  latexpdfja to make LaTeX files and run them through platex/dvipdfmx"
 	@echo "  text       to make text files"
 	@echo "  man        to make manual pages"
 	@echo "  texinfo    to make Texinfo files"
 	@echo "  info       to make Texinfo files and run them through makeinfo"
 	@echo "  gettext    to make PO message catalogs"
 	@echo "  changes    to make an overview of all changed/added/deprecated items"
+	@echo "  xml        to make Docutils-native XML files"
+	@echo "  pseudoxml  to make pseudoxml-XML files for display purposes"
 	@echo "  linkcheck  to check all external links for integrity"
 	@echo "  doctest    to run all doctests embedded in the documentation (if enabled)"
+	@echo "  coverage   to run coverage check of the documentation (if enabled)"
 
 clean:
-	-rm -rf $(BUILDDIR)/*
+	rm -rf $(BUILDDIR)/*
 
 html:
 	$(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html
@@ -81,6 +91,14 @@ qthelp:
 	@echo "To view the help file:"
 	@echo "# assistant -collectionFile $(BUILDDIR)/qthelp/subliminal.qhc"
 
+applehelp:
+	$(SPHINXBUILD) -b applehelp $(ALLSPHINXOPTS) $(BUILDDIR)/applehelp
+	@echo
+	@echo "Build finished. The help book is in $(BUILDDIR)/applehelp."
+	@echo "N.B. You won't be able to view it unless you put it in" \
+	      "~/Library/Documentation/Help or install it in your application" \
+	      "bundle."
+
 devhelp:
 	$(SPHINXBUILD) -b devhelp $(ALLSPHINXOPTS) $(BUILDDIR)/devhelp
 	@echo
@@ -108,6 +126,12 @@ latexpdf:
 	$(MAKE) -C $(BUILDDIR)/latex all-pdf
 	@echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex."
 
+latexpdfja:
+	$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
+	@echo "Running LaTeX files through platex and dvipdfmx..."
+	$(MAKE) -C $(BUILDDIR)/latex all-pdf-ja
+	@echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex."
+
 text:
 	$(SPHINXBUILD) -b text $(ALLSPHINXOPTS) $(BUILDDIR)/text
 	@echo
@@ -151,3 +175,18 @@ doctest:
 	$(SPHINXBUILD) -b doctest $(ALLSPHINXOPTS) $(BUILDDIR)/doctest
 	@echo "Testing of doctests in the sources finished, look at the " \
 	      "results in $(BUILDDIR)/doctest/output.txt."
+
+coverage:
+	$(SPHINXBUILD) -b coverage $(ALLSPHINXOPTS) $(BUILDDIR)/coverage
+	@echo "Testing of coverage in the sources finished, look at the " \
+	      "results in $(BUILDDIR)/coverage/python.txt."
+
+xml:
+	$(SPHINXBUILD) -b xml $(ALLSPHINXOPTS) $(BUILDDIR)/xml
+	@echo
+	@echo "Build finished. The XML files are in $(BUILDDIR)/xml."
+
+pseudoxml:
+	$(SPHINXBUILD) -b pseudoxml $(ALLSPHINXOPTS) $(BUILDDIR)/pseudoxml
+	@echo
+	@echo "Build finished. The pseudo-XML files are in $(BUILDDIR)/pseudoxml."

docs/_templates/sidebar-intro.html

@@ -1,4 +0,0 @@
-<h3>About</h3>
-<p>
-  Subliminal is a python library to search and download subtitles.
-</p>

docs/_templates/sidebar-links.html

@@ -1,6 +0,0 @@
-<h3>Useful Links</h3>
-<ul>
-  <li><a href="http://pypi.python.org/pypi/subliminal">subliminal @ PyPI</a></li>
-  <li><a href="http://github.com/Diaoul/subliminal">subliminal @ GitHub</a></li>
-  <li><a href="http://github.com/Diaoul/subliminal/issues">Issue Tracker</a></li>
-</ul>

docs/api/cache.rst

@@ -0,0 +1,21 @@
+Cache
+=====
+.. module:: subliminal.cache
+
+.. autodata:: SHOW_EXPIRATION_TIME
+    :annotation:
+
+.. autodata:: EPISODE_EXPIRATION_TIME
+    :annotation:
+
+.. autodata:: REFINER_EXPIRATION_TIME
+    :annotation:
+
+.. data:: region
+    :annotation:
+
+    The :class:`~dogpile.cache.region.CacheRegion`
+
+
+Refer to dogpile.cache's `region configuration documentation
+<http://dogpilecache.readthedocs.org/en/latest/usage.html#region-configuration>`_ to see how to configure the region

docs/api/cli.rst

@@ -0,0 +1,3 @@
+CLI
+===
+.. automodule:: subliminal.cli

docs/api/core.rst

@@ -0,0 +1,7 @@
+Core
+====
+.. automodule:: subliminal.core
+    :exclude-members: ARCHIVE_EXTENSIONS
+
+    .. autodata:: ARCHIVE_EXTENSIONS
+        :annotation:

docs/api/exceptions.rst

@@ -0,0 +1,3 @@
+Exceptions
+==========
+.. automodule:: subliminal.exceptions

docs/api/extensions.rst

@@ -0,0 +1,3 @@
+Extensions
+==========
+.. automodule:: subliminal.extensions

docs/api/providers.rst

@@ -0,0 +1,48 @@
+Providers
+=========
+.. automodule:: subliminal.providers
+
+Addic7ed
+--------
+.. automodule:: subliminal.providers.addic7ed
+   :private-members:
+
+LegendasTv
+----------
+.. automodule:: subliminal.providers.legendastv
+   :private-members:
+
+NapiProjekt
+-----------
+.. automodule:: subliminal.providers.napiprojekt
+   :private-members:
+
+OpenSubtitles
+-------------
+.. automodule:: subliminal.providers.opensubtitles
+   :private-members:
+
+Podnapisi
+---------
+.. automodule:: subliminal.providers.podnapisi
+   :private-members:
+
+Shooter
+-------
+.. automodule:: subliminal.providers.shooter
+   :private-members:
+
+SubsCenter
+----------
+.. automodule:: subliminal.providers.subscenter
+   :private-members:
+
+TheSubDB
+--------
+.. automodule:: subliminal.providers.thesubdb
+   :private-members:
+
+TVsubtitles
+-----------
+.. automodule:: subliminal.providers.tvsubtitles
+   :private-members:

docs/api/refiners.rst

@@ -0,0 +1,20 @@
+.. _refiners:
+
+Refiners
+========
+.. automodule:: subliminal.refiners
+
+
+Metadata
+--------
+.. autofunction:: subliminal.refiners.metadata.refine
+
+
+TVDB
+----
+.. autofunction:: subliminal.refiners.tvdb.refine
+
+
+OMDb
+----
+.. autofunction:: subliminal.refiners.omdb.refine

docs/api/score.rst

@@ -0,0 +1,3 @@
+Score
+=====
+.. automodule:: subliminal.score

docs/api/subtitle.rst

@@ -0,0 +1,7 @@
+Subtitle
+========
+.. automodule:: subliminal.subtitle
+    :exclude-members: SUBTITLE_EXTENSIONS
+
+    .. autodata:: SUBTITLE_EXTENSIONS
+        :annotation:

docs/api/utils.rst

@@ -0,0 +1,3 @@
+Utils
+=====
+.. automodule:: subliminal.utils

docs/api/video.rst

@@ -0,0 +1,7 @@
+Video
+=====
+.. automodule:: subliminal.video
+    :exclude-members: VIDEO_EXTENSIONS
+
+    .. autodata:: VIDEO_EXTENSIONS
+        :annotation:

docs/cassettes/test_usage.yaml

@@ -0,0 +1,658 @@
+interactions:
+- request:
+    body: null
+    headers:
+      Accept: ['*/*']
+      Accept-Encoding: ['gzip, deflate']
+      Connection: [keep-alive]
+      User-Agent: [Subliminal/2.0]
+    method: GET
+    uri: http://podnapisi.net/subtitles/search/old?sTS=5&sL=hu&sTE=18&sK=The+Big+Bang+Theory&sXML=1
+  response:
+    body: {string: "<html>\r\n<head><title>302 Found</title></head>\r\n<body bgcolor=\"\
+        white\">\r\n<center><h1>302 Found</h1></center>\r\n<hr><center>nginx/1.8.0</center>\r\
+        \n</body>\r\n</html>\r\n"}
+    headers:
+      Connection: [keep-alive]
+      Content-Length: ['160']
+      Content-Type: [text/html]
+      Date: ['Wed, 23 Mar 2016 09:34:06 GMT']
+      Location: ['http://www.podnapisi.net/subtitles/search/old?sTS=5&sL=hu&sTE=18&sK=The+Big+Bang+Theory&sXML=1']
+      Server: [nginx/1.8.0]
+    status: {code: 302, message: Moved Temporarily}
+- request:
+    body: null
+    headers:
+      Accept: ['*/*']
+      Accept-Encoding: ['gzip, deflate']
+      Connection: [keep-alive]
+      User-Agent: [Subliminal/2.0]
+    method: GET
+    uri: http://www.podnapisi.net/subtitles/search/old?sTS=5&sL=hu&sTE=18&sK=The+Big+Bang+Theory&sXML=1
+  response:
+    body: {string: "<html>\r\n<head><title>301 Moved Permanently</title></head>\r\n\
+        <body bgcolor=\"white\">\r\n<center><h1>301 Moved Permanently</h1></center>\r\
+        \n<hr><center>nginx/1.8.0</center>\r\n</body>\r\n</html>\r\n"}
+    headers:
+      Connection: [keep-alive]
+      Content-Length: ['184']
+      Content-Type: [text/html]
+      Date: ['Wed, 23 Mar 2016 09:34:07 GMT']
+      Location: ['https://www.podnapisi.net/subtitles/search/old?sTS=5&sL=hu&sTE=18&sK=The+Big+Bang+Theory&sXML=1']
+      Server: [nginx/1.8.0]
+    status: {code: 301, message: Moved Permanently}
+- request:
+    body: null
+    headers:
+      Accept: ['*/*']
+      Accept-Encoding: ['gzip, deflate']
+      Connection: [keep-alive]
+      User-Agent: [Subliminal/2.0]
+    method: GET
+    uri: https://www.podnapisi.net/subtitles/search/old?sTS=5&sL=hu&sTE=18&sK=The+Big+Bang+Theory&sXML=1
+  response:
+    body:
+      string: !!binary |
+        H4sIAAAAAAAAA81VWW/bRhB+z6/YKC9OIXJJHT6C8QZKpNYCHDmFhbZJUARrcU0uSi0JHpIN5Md3
+        hjecZNu+FHmRZma/2Tn2myG8ftjH7KCyXCfmcuS73ogps0sCbcLLUVncO+cjlhfSBDJOjLocPap8
+        9Fo8g+fLm7fbD+9XLFN5GRc5+/SMMXi+ul69W222nfXkxfu3y8V28SWVoTaywChf8vKu0EWsXv4k
+        0Gfo1YPYya7MMmWKMdslJf01cV7WPkOvBsnaWN+C0B1PAX22bUbsRAdjViU3Zo9KZmO2Tw5ardFa
+        ZjH+pHEiA5VVhkbeyL2i9GIlcxRiacJShpVPK9eQQhOwONwiMDEkrVKdJ0FtTNVOSwyxC/Ixu0+y
+        vcSi71NUMmybCVGJZYhqkBwNZZF/o04dPC1y2KjUflzVbfOnjtjOm17ZINhF63HX33+DorbacM2b
+        2CDtC62tjWtR/xSwxdkiEgus5w0/7JiGOXbQbc0pGwjZZjuueWhFpNYLau5aLyBW2wBGHT9X1P8a
+        NCQ3Qb5G9DPejY0NpB7krriSeaSGKf0pGDTrR0C/owQ0m0f4wFsRqnVVWWjniM5xAry7gw8vaZeP
+        AB0If3Yx92eIRRlwXsXHYvE7cJKgmk+xjRR7o0P2BvcMQyXJHoHXR0ADKiaedwa8EqGZSJF/8H4B
+        3mqAUyiiokhfcX48Ht00CYzEVaRdowre5pPzqHSKSDl3OnTuMBopGM2hAM6tN1/557xOj+6DfjeK
+        mefPT4EPLN0pjZD465DFqj+vbNioaoNSgS4W6FKBbl2gW0dzr5bb35zrm2uq+3uYs4mXVkD3YXI6
+        c5Zr/B7drm821P46ALRjusZ+z4EP1O6oSumqNKHMtDQ9pk619RBR2R/RA2Ft/nTqTfDn9IKeBQ3Q
+        bnyBsToZrc0MC/+c7K1G8HpuhVfhGwVoVLmAeiTFhi+ANzLgZ6IxoAD1zAnPRf9GhmqARIQuNG4C
+        uqHCC9EiIh1GnwN1r42mb3SNE8AHuG6AxPSCUu51GI4NpthRSEBLpo7c3gUSg9hMlL7Z/NDkrtN7
+        Sm4c9u8Se2ES87hPyrzH/Cdyu38c9NL5+dd3/ydb/elsfkbc/LHYSmTv6EdKT7jpHB+hVy3863bu
+        37blw93pCgAA
+    headers:
+      Connection: [keep-alive]
+      Content-Encoding: [gzip]
+      Content-Type: [text/xml;charset=utf-8]
+      Date: ['Wed, 23 Mar 2016 09:34:07 GMT']
+      Server: [nginx/1.8.0]
+      Vary: [Accept-Encoding]
+    status: {code: 200, message: OK}
+- request:
+    body: null
+    headers:
+      Accept: ['*/*']
+      Accept-Encoding: ['gzip, deflate']
+      Connection: [keep-alive]
+      User-Agent: [Subliminal/2.0]
+    method: GET
+    uri: http://podnapisi.net/subtitles/ZtAW/download?container=zip
+  response:
+    body: {string: "<html>\r\n<head><title>302 Found</title></head>\r\n<body bgcolor=\"\
+        white\">\r\n<center><h1>302 Found</h1></center>\r\n<hr><center>nginx/1.8.0</center>\r\
+        \n</body>\r\n</html>\r\n"}
+    headers:
+      Connection: [keep-alive]
+      Content-Length: ['160']
+      Content-Type: [text/html]
+      Date: ['Wed, 23 Mar 2016 09:34:07 GMT']
+      Location: ['http://www.podnapisi.net/subtitles/ZtAW/download?container=zip']
+      Server: [nginx/1.8.0]
+    status: {code: 302, message: Moved Temporarily}
+- request:
+    body: null
+    headers:
+      Accept: ['*/*']
+      Accept-Encoding: ['gzip, deflate']
+      Connection: [keep-alive]
+      User-Agent: [Subliminal/2.0]
+    method: GET
+    uri: http://www.podnapisi.net/subtitles/ZtAW/download?container=zip
+  response:
+    body: {string: "<html>\r\n<head><title>301 Moved Permanently</title></head>\r\n\
+        <body bgcolor=\"white\">\r\n<center><h1>301 Moved Permanently</h1></center>\r\
+        \n<hr><center>nginx/1.8.0</center>\r\n</body>\r\n</html>\r\n"}
+    headers:
+      Connection: [keep-alive]
+      Content-Length: ['184']
+      Content-Type: [text/html]
+      Date: ['Wed, 23 Mar 2016 09:34:07 GMT']
+      Location: ['https://www.podnapisi.net/subtitles/ZtAW/download?container=zip']
+      Server: [nginx/1.8.0]
+    status: {code: 301, message: Moved Permanently}
+- request:
+    body: null
+    headers:
+      Accept: ['*/*']
+      Accept-Encoding: ['gzip, deflate']
+      Connection: [keep-alive]
+      User-Agent: [Subliminal/2.0]
+    method: GET
+    uri: https://www.podnapisi.net/subtitles/ZtAW/download?container=zip
+  response:
+    body:
+      string: !!binary |
+        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
+    headers:
+      Accept-Ranges: [bytes]
+      Connection: [keep-alive]
+      Content-Disposition: [attachment; filename="e638ea178f406cb584f48051501e2cb4db4fce1d.zip"]
+      Content-Length: ['10541']
+      Content-Type: [application/octet-stream]
+      Date: ['Wed, 23 Mar 2016 09:34:07 GMT']
+      ETag: ['"4f497ffb-292d"']
+      Last-Modified: ['Sun, 26 Feb 2012 00:42:35 GMT']
+      Server: [nginx/1.8.0]
+    status: {code: 200, message: OK}
+- request:
+    body: null
+    headers:
+      Accept: ['*/*']
+      Accept-Encoding: ['gzip, deflate']
+      Connection: [keep-alive]
+      User-Agent: [Subliminal/2.0]
+    method: GET
+    uri: http://podnapisi.net/subtitles/search/old?sTS=5&sL=hu&sTE=18&sK=The+Big+Bang+Theory&sXML=1
+  response:
+    body: {string: "<html>\r\n<head><title>302 Found</title></head>\r\n<body bgcolor=\"\
+        white\">\r\n<center><h1>302 Found</h1></center>\r\n<hr><center>nginx/1.8.0</center>\r\
+        \n</body>\r\n</html>\r\n"}
+    headers:
+      Connection: [keep-alive]
+      Content-Length: ['160']
+      Content-Type: [text/html]
+      Date: ['Wed, 23 Mar 2016 09:34:07 GMT']
+      Location: ['http://www.podnapisi.net/subtitles/search/old?sTS=5&sL=hu&sTE=18&sK=The+Big+Bang+Theory&sXML=1']
+      Server: [nginx/1.8.0]
+    status: {code: 302, message: Moved Temporarily}
+- request:
+    body: null
+    headers:
+      Accept: ['*/*']
+      Accept-Encoding: ['gzip, deflate']
+      Connection: [keep-alive]
+      User-Agent: [Subliminal/2.0]
+    method: GET
+    uri: http://www.podnapisi.net/subtitles/search/old?sTS=5&sL=hu&sTE=18&sK=The+Big+Bang+Theory&sXML=1
+  response:
+    body: {string: "<html>\r\n<head><title>301 Moved Permanently</title></head>\r\n\
+        <body bgcolor=\"white\">\r\n<center><h1>301 Moved Permanently</h1></center>\r\
+        \n<hr><center>nginx/1.8.0</center>\r\n</body>\r\n</html>\r\n"}
+    headers:
+      Connection: [keep-alive]
+      Content-Length: ['184']
+      Content-Type: [text/html]
+      Date: ['Wed, 23 Mar 2016 09:34:08 GMT']
+      Location: ['https://www.podnapisi.net/subtitles/search/old?sTS=5&sL=hu&sTE=18&sK=The+Big+Bang+Theory&sXML=1']
+      Server: [nginx/1.8.0]
+    status: {code: 301, message: Moved Permanently}
+- request:
+    body: null
+    headers:
+      Accept: ['*/*']
+      Accept-Encoding: ['gzip, deflate']
+      Connection: [keep-alive]
+      User-Agent: [Subliminal/2.0]
+    method: GET
+    uri: https://www.podnapisi.net/subtitles/search/old?sTS=5&sL=hu&sTE=18&sK=The+Big+Bang+Theory&sXML=1
+  response:
+    body:
+      string: !!binary |
+        H4sIAAAAAAAAA81VWW/bRhB+z6/YKC9OIXJJHT6C8QZKpNYCHDmFhbZJUARrcU0uSi0JHpIN5Md3
+        hjecZNu+FHmRZma/2Tn2myG8ftjH7KCyXCfmcuS73ogps0sCbcLLUVncO+cjlhfSBDJOjLocPap8
+        9Fo8g+fLm7fbD+9XLFN5GRc5+/SMMXi+ul69W222nfXkxfu3y8V28SWVoTaywChf8vKu0EWsXv4k
+        0Gfo1YPYya7MMmWKMdslJf01cV7WPkOvBsnaWN+C0B1PAX22bUbsRAdjViU3Zo9KZmO2Tw5ardFa
+        ZjH+pHEiA5VVhkbeyL2i9GIlcxRiacJShpVPK9eQQhOwONwiMDEkrVKdJ0FtTNVOSwyxC/Ixu0+y
+        vcSi71NUMmybCVGJZYhqkBwNZZF/o04dPC1y2KjUflzVbfOnjtjOm17ZINhF63HX33+DorbacM2b
+        2CDtC62tjWtR/xSwxdkiEgus5w0/7JiGOXbQbc0pGwjZZjuueWhFpNYLau5aLyBW2wBGHT9X1P8a
+        NCQ3Qb5G9DPejY0NpB7krriSeaSGKf0pGDTrR0C/owQ0m0f4wFsRqnVVWWjniM5xAry7gw8vaZeP
+        AB0If3Yx92eIRRlwXsXHYvE7cJKgmk+xjRR7o0P2BvcMQyXJHoHXR0ADKiaedwa8EqGZSJF/8H4B
+        3mqAUyiiokhfcX48Ht00CYzEVaRdowre5pPzqHSKSDl3OnTuMBopGM2hAM6tN1/557xOj+6DfjeK
+        mefPT4EPLN0pjZD465DFqj+vbNioaoNSgS4W6FKBbl2gW0dzr5bb35zrm2uq+3uYs4mXVkD3YXI6
+        c5Zr/B7drm821P46ALRjusZ+z4EP1O6oSumqNKHMtDQ9pk619RBR2R/RA2Ft/nTqTfDn9IKeBQ3Q
+        bnyBsToZrc0MC/+c7K1G8HpuhVfhGwVoVLmAeiTFhi+ANzLgZ6IxoAD1zAnPRf9GhmqARIQuNG4C
+        uqHCC9EiIh1GnwN1r42mb3SNE8AHuG6AxPSCUu51GI4NpthRSEBLpo7c3gUSg9hMlL7Z/NDkrtN7
+        Sm4c9u8Se2ES87hPyrzH/Cdyu38c9NL5+dd3/ydb/elsfkbc/LHYSmTv6EdKT7jpHB+hVy3863bu
+        37blw93pCgAA
+    headers:
+      Connection: [keep-alive]
+      Content-Encoding: [gzip]
+      Content-Type: [text/xml;charset=utf-8]
+      Date: ['Wed, 23 Mar 2016 09:34:08 GMT']
+      Server: [nginx/1.8.0]
+      Vary: [Accept-Encoding]
+    status: {code: 200, message: OK}
+- request:
+    body: null
+    headers:
+      Accept: ['*/*']
+      Accept-Encoding: ['gzip, deflate']
+      Connection: [keep-alive]
+      User-Agent: [Subliminal/2.0]
+    method: GET
+    uri: http://podnapisi.net/subtitles/ZtAW/download?container=zip
+  response:
+    body: {string: "<html>\r\n<head><title>302 Found</title></head>\r\n<body bgcolor=\"\
+        white\">\r\n<center><h1>302 Found</h1></center>\r\n<hr><center>nginx/1.8.0</center>\r\
+        \n</body>\r\n</html>\r\n"}
+    headers:
+      Connection: [keep-alive]
+      Content-Length: ['160']
+      Content-Type: [text/html]
+      Date: ['Wed, 23 Mar 2016 09:34:08 GMT']
+      Location: ['http://www.podnapisi.net/subtitles/ZtAW/download?container=zip']
+      Server: [nginx/1.8.0]
+    status: {code: 302, message: Moved Temporarily}
+- request:
+    body: null
+    headers:
+      Accept: ['*/*']
+      Accept-Encoding: ['gzip, deflate']
+      Connection: [keep-alive]
+      User-Agent: [Subliminal/2.0]
+    method: GET
+    uri: http://www.podnapisi.net/subtitles/ZtAW/download?container=zip
+  response:
+    body: {string: "<html>\r\n<head><title>301 Moved Permanently</title></head>\r\n\
+        <body bgcolor=\"white\">\r\n<center><h1>301 Moved Permanently</h1></center>\r\
+        \n<hr><center>nginx/1.8.0</center>\r\n</body>\r\n</html>\r\n"}
+    headers:
+      Connection: [keep-alive]
+      Content-Length: ['184']
+      Content-Type: [text/html]
+      Date: ['Wed, 23 Mar 2016 09:34:08 GMT']
+      Location: ['https://www.podnapisi.net/subtitles/ZtAW/download?container=zip']
+      Server: [nginx/1.8.0]
+    status: {code: 301, message: Moved Permanently}
+- request:
+    body: null
+    headers:
+      Accept: ['*/*']
+      Accept-Encoding: ['gzip, deflate']
+      Connection: [keep-alive]
+      User-Agent: [Subliminal/2.0]
+    method: GET
+    uri: https://www.podnapisi.net/subtitles/ZtAW/download?container=zip
+  response:
+    body:
+      string: !!binary |
+        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
+    headers:
+      Accept-Ranges: [bytes]
+      Connection: [keep-alive]
+      Content-Disposition: [attachment; filename="e638ea178f406cb584f48051501e2cb4db4fce1d.zip"]
+      Content-Length: ['10541']
+      Content-Type: [application/octet-stream]
+      Date: ['Wed, 23 Mar 2016 09:34:08 GMT']
+      ETag: ['"4f497ffb-292d"']
+      Last-Modified: ['Sun, 26 Feb 2012 00:42:35 GMT']
+      Server: [nginx/1.8.0]
+    status: {code: 200, message: OK}
+version: 1

docs/conf.py

@@ -1,9 +1,11 @@
+#!/usr/bin/env python3
 # -*- coding: utf-8 -*-
 #
 # subliminal documentation build configuration file, created by
-# sphinx-quickstart on Tue Feb 28 16:33:06 2012.
+# sphinx-quickstart on Sat Jul 11 00:40:28 2015.
 #
-# This file is execfile()d with the current directory set to its containing dir.
+# This file is execfile()d with the current directory set to its
+# containing dir.
 #
 # Note that not all possible configuration values are present in this
 # autogenerated file.
@@ -11,28 +13,41 @@
 # All configuration values have a default; values that are commented out
 # serve to show the default.
 
-import sys, os
+import sys
+import os
+import shlex
+import sphinx_rtd_theme
 
 # If extensions (or modules to document with autodoc) are in another directory,
 # add these directories to sys.path here. If the directory is relative to the
 # documentation root, use os.path.abspath to make it absolute, like shown here.
 sys.path.insert(0, os.path.abspath('..'))
-sys.path.append(os.path.abspath('_themes'))
-import subliminal.infos
+import subliminal
 
-# -- General configuration -----------------------------------------------------
+# -- General configuration ------------------------------------------------
 
 # If your documentation needs a minimal Sphinx version, state it here.
 #needs_sphinx = '1.0'
 
-# Add any Sphinx extension module names here, as strings. They can be extensions
-# coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
-extensions = ['sphinx.ext.autodoc']
+# If true, Sphinx will warn about all references where the target cannot be found.
+nitpicky = True
+
+# Add any Sphinx extension module names here, as strings. They can be
+# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
+# ones.
+extensions = [
+    'sphinx.ext.autodoc',
+    'sphinx.ext.intersphinx',
+    'sphinx.ext.viewcode',
+    'sphinxcontrib.programoutput',
+]
 
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ['_templates']
 
-# The suffix of source filenames.
+# The suffix(es) of source filenames.
+# You can specify multiple suffix as a list of string:
+# source_suffix = ['.rst', '.md']
 source_suffix = '.rst'
 
 # The encoding of source files.
@@ -42,21 +57,25 @@ source_suffix = '.rst'
 master_doc = 'index'
 
 # General information about the project.
-project = u'subliminal'
-copyright = u'2012, Antoine Bertin'
+project = subliminal.__title__
+copyright = ' '.join(subliminal.__copyright__.split()[1:])
+author = subliminal.__copyright__.split(', ')[1]
 
 # The version info for the project you're documenting, acts as replacement for
 # |version| and |release|, also used in various other places throughout the
 # built documents.
 #
 # The short X.Y version.
-version = subliminal.infos.__version__
+version = subliminal.__version__.split('-')[0]
 # The full version, including alpha/beta/rc tags.
-release = version
+release = subliminal.__version__
 
 # The language for content autogenerated by Sphinx. Refer to documentation
 # for a list of supported languages.
-#language = None
+#
+# This is also used if you do content translation via gettext catalogs.
+# Usually you set "language" from the command line for these cases.
+language = None
 
 # There are two options for replacing |today|: either, you set today to some
 # non-false value, then it is used:
@@ -68,7 +87,8 @@ release = version
 # directories to ignore when looking for source files.
 exclude_patterns = ['_build']
 
-# The reST default role (used for this markup: `text`) to use for all documents.
+# The reST default role (used for this markup: `text`) to use for all
+# documents.
 #default_role = None
 
 # If true, '()' will be appended to :func: etc. cross-reference text.
@@ -88,25 +108,32 @@ pygments_style = 'sphinx'
 # A list of ignored prefixes for module index sorting.
 #modindex_common_prefix = []
 
+# If true, keep warnings as "system message" paragraphs in the built documents.
+#keep_warnings = False
 
-# -- Options for HTML output ---------------------------------------------------
+# If true, `todo` and `todoList` produce output, else they produce nothing.
+todo_include_todos = False
+
+
+# -- Options for HTML output ----------------------------------------------
 
 # The theme to use for HTML and HTML Help pages.  See the documentation for
 # a list of builtin themes.
-html_theme = 'diaoul'
+html_theme = 'sphinx_rtd_theme'
 
 # Theme options are theme-specific and customize the look and feel of a theme
 # further.  For a list of options available for each theme, see the
 # documentation.
-html_theme_options = {'github_user': 'Diaoul',
-                      'github_repo': 'subliminal',
-                      'github_branch': 'develop',
-                      'fork_me': 1,
-                      'flattr_href': 'http://subliminal.readthedocs.org/',
-                      'flattr_thing_url': 'http://flattr.com/thing/629842/Subliminal'}
+#html_theme_options = {}
+# html_theme_options = {
+#     'github_user': 'Diaoul',
+#     'github_repo': project,
+#     'travis_button': True,
+#     'gratipay_user': 'Diaoul'
+# }
 
 # Add any paths that contain custom themes here, relative to this directory.
-html_theme_path = ['_themes']
+html_theme_path = [sphinx_rtd_theme.get_html_theme_path()]
 
 # The name for this set of Sphinx documents.  If None, it defaults to
 # "<project> v<release> documentation".
@@ -117,7 +144,7 @@ html_theme_path = ['_themes']
 
 # The name of an image file (relative to this directory) to place at the top
 # of the sidebar.
-html_logo = '_static/subliminal-logo.png'
+#html_logo = None
 
 # The name of an image file (within the static path) to use as favicon of the
 # docs.  This file should be a Windows icon file (.ico) being 16x16 or 32x32
@@ -129,6 +156,11 @@ html_logo = '_static/subliminal-logo.png'
 # so a file named "default.css" will overwrite the builtin "default.css".
 html_static_path = ['_static']
 
+# Add any extra paths that contain custom files (such as robots.txt or
+# .htaccess) here, relative to this directory. These files are copied
+# directly to the root of the documentation.
+#html_extra_path = []
+
 # If not '', a 'Last updated on:' timestamp is inserted at every page bottom,
 # using the given strftime format.
 #html_last_updated_fmt = '%b %d, %Y'
@@ -138,10 +170,7 @@ html_static_path = ['_static']
 #html_use_smartypants = True
 
 # Custom sidebar templates, maps document names to template names.
-html_sidebars = {
-    'index':    ['sidebar-intro.html', 'sidebar-watch.html', 'sidebar-travis-ci.html', 'sidebar-donate.html', 'localtoc.html', 'sidebar-links.html', 'searchbox.html'],
-    '**':       ['localtoc.html', 'relations.html', 'sourcelink.html']
-    }
+#html_sidebars = {}
 
 # Additional templates that should be rendered to pages, maps page names to
 # template names.
@@ -173,11 +202,24 @@ html_sidebars = {
 # This is the file name suffix for HTML files (e.g. ".xhtml").
 #html_file_suffix = None
 
+# Language to be used for generating the HTML full-text search index.
+# Sphinx supports the following languages:
+#   'da', 'de', 'en', 'es', 'fi', 'fr', 'h', 'it', 'ja'
+#   'nl', 'no', 'pt', 'ro', 'r', 'sv', 'tr'
+#html_search_language = 'en'
+
+# A dictionary with options for the search language support, empty by default.
+# Now only 'ja' uses this config value
+#html_search_options = {'type': 'default'}
+
+# The name of a javascript file (relative to the configuration directory) that
+# implements a search results scorer. If empty, the default will be used.
+#html_search_scorer = 'scorer.js'
+
 # Output file base name for HTML help builder.
-htmlhelp_basename = 'subliminaldoc'
+htmlhelp_basename = project + 'doc'
 
-
-# -- Options for LaTeX output --------------------------------------------------
+# -- Options for LaTeX output ---------------------------------------------
 
 latex_elements = {
 # The paper size ('letterpaper' or 'a4paper').
@@ -188,13 +230,17 @@ latex_elements = {
 
 # Additional stuff for the LaTeX preamble.
 #'preamble': '',
+
+# Latex figure (float) alignment
+#'figure_align': 'htbp',
 }
 
 # Grouping the document tree into LaTeX files. List of tuples
-# (source start file, target name, title, author, documentclass [howto/manual]).
+# (source start file, target name, title,
+#  author, documentclass [howto, manual, or own class]).
 latex_documents = [
-  ('index', 'subliminal.tex', u'subliminal Documentation',
-   u'Antoine Bertin', 'manual'),
+    (master_doc, project + '.tex', project + ' Documentation',
+     author, 'manual'),
 ]
 
 # The name of an image file (relative to this directory) to place at the top of
@@ -218,28 +264,28 @@ latex_documents = [
 #latex_domain_indices = True
 
 
-# -- Options for manual page output --------------------------------------------
+# -- Options for manual page output ---------------------------------------
 
 # One entry per manual page. List of tuples
 # (source start file, name, description, authors, manual section).
 man_pages = [
-    ('index', 'subliminal', u'subliminal Documentation',
-     [u'Antoine Bertin'], 1)
+    (master_doc, project, project + ' Documentation',
+     [author], 1)
 ]
 
 # If true, show URL addresses after external links.
 #man_show_urls = False
 
 
-# -- Options for Texinfo output ------------------------------------------------
+# -- Options for Texinfo output -------------------------------------------
 
 # Grouping the document tree into Texinfo files. List of tuples
 # (source start file, target name, title, author,
 #  dir menu entry, description, category)
 texinfo_documents = [
-  ('index', 'subliminal', u'subliminal Documentation',
-   u'Antoine Bertin', 'subliminal', 'One line description of project.',
-   'Miscellaneous'),
+    (master_doc, project, project + ' Documentation',
+     author, project, 'Subtitles, faster than your thoughts',
+     'Miscellaneous'),
 ]
 
 # Documents to append as an appendix to all manuals.
@@ -251,5 +297,24 @@ texinfo_documents = [
 # How to display URL addresses: 'footnote', 'no', or 'inline'.
 #texinfo_show_urls = 'footnote'
 
+# If true, do not generate a @detailmenu in the "Top" node's menu.
+#texinfo_no_detailmenu = False
+
+
+# Example configuration for intersphinx: refer to the Python standard library.
+intersphinx_mapping = {
+    'python': ('http://docs.python.org/3.5', None),
+    'guessit': ('http://guessit.readthedocs.org/en/latest', None),
+    'babelfish': ('http://babelfish.readthedocs.org/en/latest', None),
+    'dogpilecache': ('http://dogpilecache.readthedocs.org/en/latest', None),
+    'dogpilecore': ('http://dogpilecore.readthedocs.org/en/latest', None),
+    'stevedore': ('http://docs.openstack.org/developer/stevedore', None),
+    'click': ('http://click.pocoo.org/4', None),
+    'rarfile': ('http://rarfile.readthedocs.org/en/latest/', None)
+}
+
+
 # -- Options for autodoc -------------------------------------------------------
 autodoc_member_order = 'bysource'
+
+autodoc_default_flags = ['members']

docs/conftest.py

@@ -0,0 +1,40 @@
+# -*- coding: utf-8 -*-
+import os
+import sys
+
+import pytest
+try:
+    from unittest.mock import Mock
+except ImportError:
+    from mock import Mock
+from vcr import VCR
+
+from subliminal.cache import region
+
+vcr = VCR(path_transformer=lambda path: path + '.yaml',
+          record_mode=os.environ.get('VCR_RECORD_MODE', 'once'),
+          match_on=['method', 'scheme', 'host', 'port', 'path', 'query', 'body'],
+          cassette_library_dir=os.path.realpath(os.path.join('docs', 'cassettes')))
+
+
+@pytest.fixture(autouse=True, scope='session')
+def configure_region():
+    region.configure('dogpile.cache.null')
+    region.configure = Mock()
+
+
+@pytest.fixture(autouse=True)
+def chdir(tmpdir, monkeypatch):
+    monkeypatch.chdir(str(tmpdir))
+
+
+@pytest.yield_fixture(autouse=True)
+def use_cassette(request):
+    with vcr.use_cassette('test_' + request.fspath.purebasename):
+        yield
+
+
+@pytest.fixture(autouse=True)
+def skip_python_2():
+    if sys.version_info < (3, 0):
+        return pytest.skip('Requires python 3')

docs/dev.rst

@@ -1,98 +0,0 @@
-This guide is going to explain the main logic of subliminal and detail
-every class or function.
-
-Services
---------
-Subliminal aims at downloading subtitles. Over the web, one can find subtitles
-combining different websites but there is no guarantee of a perfect match.
-Even if OpenSubtitles has a gigantic subtitles database, you may not be able to
-find a subtitle on it but you will find it elsewhere, say BierDopje. Sometimes,
-it just takes some time before it shows up on a website even if already available
-on another, but you do not want to wait to watch the latest Big Bang Theory, right?
-
-Given this, to be reliable, subliminal has to use different :mod:`~subliminal.services`
-and use a unified method to gather them all. The :class:`~subliminal.services.ServiceBase`
-class will achieve this.
-
-.. automodule:: subliminal.services
-    :members:
-
-Languages
----------
-To be able to support many languages, subliminal makes heavy use of ISO-3166 and ISO-639
-in a dedicated module.
-
-.. automodule:: subliminal.language
-    :members:
-    
-    .. data:: subliminal.language.COUNTRIES
-
-        ISO-3166-1 countries list from `Debian package iso-codes 3.36-1 <http://packages.debian.org/fr/sid/iso-codes>`_.
-        Each item of this list is a tuple like ``(‘alpha2’, ‘alpha3’, ‘numeric’, ‘name’)``
-    
-    .. data:: subliminal.language.LANGUAGES
-
-        ISO-639-2 languages list from `the official source <http://www.loc.gov/standards/iso639-2/ISO-639-2_utf-8.txt>`_.
-        Each item of this list is a tuple like ``(‘alpha3’, ‘terminologic’, ‘alpha2’, ‘name’, ‘french_name’)``
-    
-
-Tasks
------
-Subliminal is IO bound: it mostly waits for IO operations (web requests) to complete.
-Thus, subliminal is a good place for multi-threading. It works with atomic operations
-represented by a :class:`~subliminal.tasks.Task` class which can be consumed with
-:func:`~subliminal.core.consume_task` but we'll see that later.
-
-.. automodule:: subliminal.tasks
-    :members:
-
-Asynchronous
-------------
-To consume those tasks in an asynchronous way without flooding services with requests,
-subliminal uses multiple instances of the :class:`~subliminal.async.Worker` class that
-will consume the same task queue. Each worker will only create a single instance of each
-:mod:`service <subliminal.services>` and this save some initialization time.
-The :class:`~subliminal.async.Pool` is here to instantiate and manage multiple workers
-at a time.
-
-.. automodule:: subliminal.async
-    :members:
-
-Core
-----
-The goal of subliminal's :mod:`~subliminal.core` module is to merge results from
-consumed tasks. Merging has to be intelligent and take user preferences into account.
-Core module is thus responsible for the computation of a :func:`matching confidence
-<subliminal.core.matching_confidence>` so the user knows the chances that the
-:class:`~subliminal.subtitles.ResultSubtitle` matches the :class:`~subliminal.videos.Video`
-
-.. automodule:: subliminal.core
-    :members:
-
-Other objects
--------------
-Subliminal uses some other self-explanatory functions and classes listed below.
-
-Video
-^^^^^
-
-.. automodule:: subliminal.videos
-    :members:
-
-Subtitle
-^^^^^^^^
-
-.. automodule:: subliminal.subtitles
-    :members:
-
-Utilities
-^^^^^^^^^
-
-.. automodule:: subliminal.utils
-    :members:
-
-Exceptions
-^^^^^^^^^^
-
-.. automodule:: subliminal.exceptions
-    :members:

docs/index.rst

@@ -1,79 +1,52 @@
 .. subliminal documentation master file, created by
-   sphinx-quickstart on Tue Feb 28 16:33:06 2012.
+   sphinx-quickstart on Sat Jul 11 00:40:28 2015.
    You can adapt this file completely to your liking, but it should at least
    contain the root `toctree` directive.
 
-Subliminal
-==========
-Release v\ |version|
+Welcome to subliminal!
+======================
+Subliminal is a python 2.7+ library to search and download subtitles.
+It comes with an easy to use yet powerful :abbr:`CLI (command-line interface)` suitable for direct use or cron jobs.
 
-Subliminal is a python library to search and download subtitles.
-
-It uses video hashes and the powerful `guessit <http://guessit.readthedocs.org/>`_ library
-that extracts informations from filenames or filepaths to ensure you have the best subtitles.
-It also relies on `enzyme <https://github.com/Diaoul/enzyme>`_ to detect embedded subtitles
-and avoid duplicates.
-
-Features
---------
-Multiple subtitles services are available:
-
-* Addic7ed
-* BierDopje
-* OpenSubtitles
-* SubsWiki
-* Subtitulos
-* TheSubDB
-* TvSubtitles
-
-You can use main subliminal's functions with a **file path**, a **file name** or a **folder path**.
-
-CLI
-^^^
-Download english subtitles::
-
-    $ subliminal -l en The.Big.Bang.Theory.S05E18.HDTV.x264-LOL.mp4
-    **************************************************
-    Downloaded 1 subtitle(s) for 1 video(s)
-    The.Big.Bang.Theory.S05E18.HDTV.x264-LOL.srt from opensubtitles
-    **************************************************
-
-Module
-^^^^^^
-List english subtitles::
-
-	>>> subliminal.list_subtitles('The.Big.Bang.Theory.S05E18.HDTV.x264-LOL.mp4', ['en'])
-
-Multi-threaded use
-^^^^^^^^^^^^^^^^^^
-Use 4 workers to achieve the same result::
-
-	>>> with subliminal.Pool(4) as p:
-	... 	p.list_subtitles('The.Big.Bang.Theory.S05E18.HDTV.x264-LOL.mp4', ['en'])
-
-User Guide
-----------
-This part of the documentation details how to use subliminal for most common tasks
 
+Documentation
+-------------
 .. toctree::
-   :maxdepth: 2
-   
-   user
+    :maxdepth: 2
 
-Developer Guide
----------------
-This part of the documentation explains internal behavior of subliminal and its algorithms
-
-.. toctree::
-   :maxdepth: 2
-   
-   dev
+    user/usage
+    user/how_it_works
+    user/cli
+    user/provider_guide
 
 
 API Documentation
 -----------------
-Most common subliminal features are listed here
+If you are looking for information on a specific function, class or method, this part of the documentation is for you.
 
-.. automodule:: subliminal
-    :members:
-    :noindex:
+.. toctree::
+    :maxdepth: 1
+
+    api/core
+    api/video
+    api/subtitle
+    api/providers
+    api/refiners
+    api/extensions
+    api/score
+    api/utils
+    api/cache
+    api/cli
+    api/exceptions
+
+
+License
+-------
+MIT
+
+
+Indices and tables
+==================
+* :ref:`genindex`
+* :ref:`modindex`
+* :ref:`search`

docs/make.bat

@@ -0,0 +1,263 @@
+@ECHO OFF
+
+REM Command file for Sphinx documentation
+
+if "%SPHINXBUILD%" == "" (
+	set SPHINXBUILD=sphinx-build
+)
+set BUILDDIR=_build
+set ALLSPHINXOPTS=-d %BUILDDIR%/doctrees %SPHINXOPTS% .
+set I18NSPHINXOPTS=%SPHINXOPTS% .
+if NOT "%PAPER%" == "" (
+	set ALLSPHINXOPTS=-D latex_paper_size=%PAPER% %ALLSPHINXOPTS%
+	set I18NSPHINXOPTS=-D latex_paper_size=%PAPER% %I18NSPHINXOPTS%
+)
+
+if "%1" == "" goto help
+
+if "%1" == "help" (
+	:help
+	echo.Please use `make ^<target^>` where ^<target^> is one of
+	echo.  html       to make standalone HTML files
+	echo.  dirhtml    to make HTML files named index.html in directories
+	echo.  singlehtml to make a single large HTML file
+	echo.  pickle     to make pickle files
+	echo.  json       to make JSON files
+	echo.  htmlhelp   to make HTML files and a HTML help project
+	echo.  qthelp     to make HTML files and a qthelp project
+	echo.  devhelp    to make HTML files and a Devhelp project
+	echo.  epub       to make an epub
+	echo.  latex      to make LaTeX files, you can set PAPER=a4 or PAPER=letter
+	echo.  text       to make text files
+	echo.  man        to make manual pages
+	echo.  texinfo    to make Texinfo files
+	echo.  gettext    to make PO message catalogs
+	echo.  changes    to make an overview over all changed/added/deprecated items
+	echo.  xml        to make Docutils-native XML files
+	echo.  pseudoxml  to make pseudoxml-XML files for display purposes
+	echo.  linkcheck  to check all external links for integrity
+	echo.  doctest    to run all doctests embedded in the documentation if enabled
+	echo.  coverage   to run coverage check of the documentation if enabled
+	goto end
+)
+
+if "%1" == "clean" (
+	for /d %%i in (%BUILDDIR%\*) do rmdir /q /s %%i
+	del /q /s %BUILDDIR%\*
+	goto end
+)
+
+
+REM Check if sphinx-build is available and fallback to Python version if any
+%SPHINXBUILD% 2> nul
+if errorlevel 9009 goto sphinx_python
+goto sphinx_ok
+
+:sphinx_python
+
+set SPHINXBUILD=python -m sphinx.__init__
+%SPHINXBUILD% 2> nul
+if errorlevel 9009 (
+	echo.
+	echo.The 'sphinx-build' command was not found. Make sure you have Sphinx
+	echo.installed, then set the SPHINXBUILD environment variable to point
+	echo.to the full path of the 'sphinx-build' executable. Alternatively you
+	echo.may add the Sphinx directory to PATH.
+	echo.
+	echo.If you don't have Sphinx installed, grab it from
+	echo.http://sphinx-doc.org/
+	exit /b 1
+)
+
+:sphinx_ok
+
+
+if "%1" == "html" (
+	%SPHINXBUILD% -b html %ALLSPHINXOPTS% %BUILDDIR%/html
+	if errorlevel 1 exit /b 1
+	echo.
+	echo.Build finished. The HTML pages are in %BUILDDIR%/html.
+	goto end
+)
+
+if "%1" == "dirhtml" (
+	%SPHINXBUILD% -b dirhtml %ALLSPHINXOPTS% %BUILDDIR%/dirhtml
+	if errorlevel 1 exit /b 1
+	echo.
+	echo.Build finished. The HTML pages are in %BUILDDIR%/dirhtml.
+	goto end
+)
+
+if "%1" == "singlehtml" (
+	%SPHINXBUILD% -b singlehtml %ALLSPHINXOPTS% %BUILDDIR%/singlehtml
+	if errorlevel 1 exit /b 1
+	echo.
+	echo.Build finished. The HTML pages are in %BUILDDIR%/singlehtml.
+	goto end
+)
+
+if "%1" == "pickle" (
+	%SPHINXBUILD% -b pickle %ALLSPHINXOPTS% %BUILDDIR%/pickle
+	if errorlevel 1 exit /b 1
+	echo.
+	echo.Build finished; now you can process the pickle files.
+	goto end
+)
+
+if "%1" == "json" (
+	%SPHINXBUILD% -b json %ALLSPHINXOPTS% %BUILDDIR%/json
+	if errorlevel 1 exit /b 1
+	echo.
+	echo.Build finished; now you can process the JSON files.
+	goto end
+)
+
+if "%1" == "htmlhelp" (
+	%SPHINXBUILD% -b htmlhelp %ALLSPHINXOPTS% %BUILDDIR%/htmlhelp
+	if errorlevel 1 exit /b 1
+	echo.
+	echo.Build finished; now you can run HTML Help Workshop with the ^
+.hhp project file in %BUILDDIR%/htmlhelp.
+	goto end
+)
+
+if "%1" == "qthelp" (
+	%SPHINXBUILD% -b qthelp %ALLSPHINXOPTS% %BUILDDIR%/qthelp
+	if errorlevel 1 exit /b 1
+	echo.
+	echo.Build finished; now you can run "qcollectiongenerator" with the ^
+.qhcp project file in %BUILDDIR%/qthelp, like this:
+	echo.^> qcollectiongenerator %BUILDDIR%\qthelp\subliminal.qhcp
+	echo.To view the help file:
+	echo.^> assistant -collectionFile %BUILDDIR%\qthelp\subliminal.ghc
+	goto end
+)
+
+if "%1" == "devhelp" (
+	%SPHINXBUILD% -b devhelp %ALLSPHINXOPTS% %BUILDDIR%/devhelp
+	if errorlevel 1 exit /b 1
+	echo.
+	echo.Build finished.
+	goto end
+)
+
+if "%1" == "epub" (
+	%SPHINXBUILD% -b epub %ALLSPHINXOPTS% %BUILDDIR%/epub
+	if errorlevel 1 exit /b 1
+	echo.
+	echo.Build finished. The epub file is in %BUILDDIR%/epub.
+	goto end
+)
+
+if "%1" == "latex" (
+	%SPHINXBUILD% -b latex %ALLSPHINXOPTS% %BUILDDIR%/latex
+	if errorlevel 1 exit /b 1
+	echo.
+	echo.Build finished; the LaTeX files are in %BUILDDIR%/latex.
+	goto end
+)
+
+if "%1" == "latexpdf" (
+	%SPHINXBUILD% -b latex %ALLSPHINXOPTS% %BUILDDIR%/latex
+	cd %BUILDDIR%/latex
+	make all-pdf
+	cd %~dp0
+	echo.
+	echo.Build finished; the PDF files are in %BUILDDIR%/latex.
+	goto end
+)
+
+if "%1" == "latexpdfja" (
+	%SPHINXBUILD% -b latex %ALLSPHINXOPTS% %BUILDDIR%/latex
+	cd %BUILDDIR%/latex
+	make all-pdf-ja
+	cd %~dp0
+	echo.
+	echo.Build finished; the PDF files are in %BUILDDIR%/latex.
+	goto end
+)
+
+if "%1" == "text" (
+	%SPHINXBUILD% -b text %ALLSPHINXOPTS% %BUILDDIR%/text
+	if errorlevel 1 exit /b 1
+	echo.
+	echo.Build finished. The text files are in %BUILDDIR%/text.
+	goto end
+)
+
+if "%1" == "man" (
+	%SPHINXBUILD% -b man %ALLSPHINXOPTS% %BUILDDIR%/man
+	if errorlevel 1 exit /b 1
+	echo.
+	echo.Build finished. The manual pages are in %BUILDDIR%/man.
+	goto end
+)
+
+if "%1" == "texinfo" (
+	%SPHINXBUILD% -b texinfo %ALLSPHINXOPTS% %BUILDDIR%/texinfo
+	if errorlevel 1 exit /b 1
+	echo.
+	echo.Build finished. The Texinfo files are in %BUILDDIR%/texinfo.
+	goto end
+)
+
+if "%1" == "gettext" (
+	%SPHINXBUILD% -b gettext %I18NSPHINXOPTS% %BUILDDIR%/locale
+	if errorlevel 1 exit /b 1
+	echo.
+	echo.Build finished. The message catalogs are in %BUILDDIR%/locale.
+	goto end
+)
+
+if "%1" == "changes" (
+	%SPHINXBUILD% -b changes %ALLSPHINXOPTS% %BUILDDIR%/changes
+	if errorlevel 1 exit /b 1
+	echo.
+	echo.The overview file is in %BUILDDIR%/changes.
+	goto end
+)
+
+if "%1" == "linkcheck" (
+	%SPHINXBUILD% -b linkcheck %ALLSPHINXOPTS% %BUILDDIR%/linkcheck
+	if errorlevel 1 exit /b 1
+	echo.
+	echo.Link check complete; look for any errors in the above output ^
+or in %BUILDDIR%/linkcheck/output.txt.
+	goto end
+)
+
+if "%1" == "doctest" (
+	%SPHINXBUILD% -b doctest %ALLSPHINXOPTS% %BUILDDIR%/doctest
+	if errorlevel 1 exit /b 1
+	echo.
+	echo.Testing of doctests in the sources finished, look at the ^
+results in %BUILDDIR%/doctest/output.txt.
+	goto end
+)
+
+if "%1" == "coverage" (
+	%SPHINXBUILD% -b coverage %ALLSPHINXOPTS% %BUILDDIR%/coverage
+	if errorlevel 1 exit /b 1
+	echo.
+	echo.Testing of coverage in the sources finished, look at the ^
+results in %BUILDDIR%/coverage/python.txt.
+	goto end
+)
+
+if "%1" == "xml" (
+	%SPHINXBUILD% -b xml %ALLSPHINXOPTS% %BUILDDIR%/xml
+	if errorlevel 1 exit /b 1
+	echo.
+	echo.Build finished. The XML files are in %BUILDDIR%/xml.
+	goto end
+)
+
+if "%1" == "pseudoxml" (
+	%SPHINXBUILD% -b pseudoxml %ALLSPHINXOPTS% %BUILDDIR%/pseudoxml
+	if errorlevel 1 exit /b 1
+	echo.
+	echo.Build finished. The pseudo-XML files are in %BUILDDIR%/pseudoxml.
+	goto end
+)
+
+:end

docs/user.rst

@@ -1,118 +0,0 @@
-There are 4 different ways of using subliminal and each one is described in a dedicated section below.
-
-First, here are some basics
-
-Basics
-------
-Services
-^^^^^^^^
-You can use subliminal with multiple services to get the best result.
-Current available services are available in the :data:`subliminal.SERVICES` variable.
-
-.. autodata:: subliminal.SERVICES
-
-Languages
-^^^^^^^^^
-Subliminal supports multiple languages representations based on `ISO-639 <http://en.wikipedia.org/wiki/ISO_639>`_
-and `ISO-3166 <http://en.wikipedia.org/wiki/ISO_3166>`_. Any single ISO-639 string or combination of ISO-639 and
-ISO-3166 is acceptable. For example, you can use ``pt-br`` for Portuguese (Brazil) or ``en`` for English.
-
-Paths
-^^^^^
-All paths parameters in subliminal most commont functions can be either *a file path*,
-*a file name* or a *folder path*
-
-* File path (existing): hashes of the file will be computed and used during the search for services that
-  supports this functionnality.
-* File name (or non-existing file path): the guessit python library will be used to guess informations
-  and a text-based search will be done with services.
-* Folder path (containing video files): the given folder will be searched for video files using their
-  :data:`~subliminal.videos.MIMETYPES` and/or :data:`~subliminal.videos.EXTENSIONS`.
-  The default maximum depth to scan is 3
-
-CLI
----
-Subliminal is shipped with a Command Line Interface that allows you to
-download subtitles for one or more videos in a multithreaded way.
-
-.. note::
-
-    The cache directory defaults to *~/.config/subliminal*. Even on Windows
-
-Usage
-^^^^^
-You can have the documentation of the CLI using ``subliminal --help``::
-
-    usage: subliminal [-h] [-l LG] [-s NAME] [-m] [-f] [-w N] [-a AGE] [-c]
-                      [-q | -v] [--cache-dir DIR | --no-cache-dir] [--version]
-                      PATH [PATH ...]
-
-    Subtitles, faster than your thoughts
-
-    positional arguments:
-      PATH                  path to video file or folder
-
-    optional arguments:
-      -h, --help            show this help message and exit
-      -l LG, --language LG  wanted language (ISO 639-1)
-      -s NAME, --service NAME
-                            service to use
-      -m, --multi           download multiple subtitle languages
-      -f, --force           replace existing subtitle file
-      -w N, --workers N     use N threads (default: 4)
-      -a AGE, --age AGE     scan only for files newer or older (prefix with +)
-                            than AGE (e.g. 12h, 1w2d, +3d6h)
-      -c, --compatibility   try not to use unicode (use this if you have encoding
-                            errors)
-      -q, --quiet           disable output
-      -v, --verbose         verbose output
-      --cache-dir DIR       cache directory to use
-      --no-cache-dir        do not use cache directory (some services may not
-                            work)
-      --version             show program's version number and exit
-
-Cron job
-^^^^^^^^
-This CLI is well suited for automatic subtitles downloads. For example, to download english and french
-subtitles for videos newer than one week under /path/to/videos/ each day at 1:00AM with a single worker,
-you can use the following crontab line::
-
-    0 1 * * * user /path/to/subliminal -m -l en -l fr -w 1 -a 1w -q /path/to/videos/
-
-Simple module use
------------------
-Subliminal comes with two basic functions to search and download subtitles. For example, you
-can do::
-
-    >>> subliminal.list_subtitles('The.Big.Bang.Theory.S05E18.HDTV.x264-LOL.mp4', ['en'])
-
-.. autofunction:: subliminal.list_subtitles
-
-Or even download missing subtitles for each episodes under the given folders in two different languages::
-
-    >>> subliminal.download_subtitles(['/mnt/videos/BBT/Season 05', '/mnt/videos/HIMYM/Season 07'],
-    ...                               ['en', 'fr'], force=False, multi=True)
-
-.. autofunction:: subliminal.download_subtitles
-
-Multi-threaded module use
--------------------------
-You can call the same functions on a :class:`subliminal.Pool` object previously
-created with the appropriate number of workers.
-
-.. autoclass:: subliminal.Pool
-    :members:
-
-You have to call the :meth:`~subliminal.Pool.start` method before any actions and
-:meth:`~subliminal.Pool.stop` before exiting your program::
-
-    >>> p = subliminal.Pool(4)
-    ... p.start()
-    ... p.list_subtitles('The.Big.Bang.Theory.S05E18.HDTV.x264-LOL.mp4', ['en'])
-    ... p.stop()
-
-To make the use of :class:`~subliminal.Pool` easier, you can use the ``with`` statement
-that takes care of that for you::
-
-    >>> with subliminal.Pool(4) as p:
-    ...     p.list_subtitles('The.Big.Bang.Theory.S05E18.HDTV.x264-LOL.mp4', ['en'])

docs/user/cli.rst

@@ -0,0 +1,18 @@
+.. _cli:
+
+CLI
+===
+
+subliminal
+----------
+.. program-output:: subliminal --help
+
+
+subliminal download
+-------------------
+.. program-output:: subliminal download --help
+
+
+subliminal cache
+----------------
+.. program-output:: subliminal cache --help

docs/user/how_it_works.rst

@@ -0,0 +1,52 @@
+How it works
+============
+
+Providers
+---------
+Subliminal uses multiple providers to give users a vast choice and have a better chance to find the best matching
+subtitles. Current supported providers are:
+
+* Addic7ed
+* LegendasTV
+* NapiProjekt
+* OpenSubtitles
+* Podnapisi
+* Shooter
+* SubsCenter
+* TheSubDB
+* TvSubtitles
+
+Providers all inherit the same :class:`~subliminal.providers.Provider` base class and thus share the same API.
+They are registered on the ``subliminal.providers`` entry point and are exposed through the
+:data:`~subliminal.extensions.provider_manager` for easy access.
+
+To work with multiple providers seamlessly, the :class:`~subliminal.core.ProviderPool` exposes the same API but
+distributes it to its providers and :class:`~subliminal.core.AsyncProviderPool` does it asynchronously.
+
+.. _scoring:
+
+Scoring
+-------
+Rating subtitles and comparing them is probably the most difficult part and this is where subliminal excels with its
+powerful scoring algorithm.
+
+Using `guessit <http://guessit.readthedocs.org>`_ and `enzyme <http://enzyme.readthedocs.org>`_, subliminal extracts
+properties of the video and match them with the properties of the subtitles found with the providers.
+
+Equations in :mod:`subliminal.score` give a score to each property (called a match). The more matches the video and
+the subtitle have, the higher the score computed with :func:`~subliminal.score.compute_score` gets.
+
+
+Libraries
+---------
+Various libraries are used by subliminal and are key to its success:
+
+* `guessit <http://guessit.readthedocs.org>`_ to guess information from filenames
+* `enzyme <http://enzyme.readthedocs.org>`_ to detect embedded subtitles in videos and read other video metadata
+* `babelfish <http://babelfish.readthedocs.org>`_ to work with languages
+* `requests <http://docs.python-requests.org>`_ to make human readable HTTP requests
+* `BeautifulSoup <http://www.crummy.com/software/BeautifulSoup>`_ to parse HTML and XML
+* `dogpile.cache <http://dogpilecache.readthedocs.org>`_ to cache intermediate search results
+* `stevedore <http://docs.openstack.org/developer/stevedore/>`_ to manage the provider entry point
+* `chardet <http://chardet.readthedocs.org>`_ to detect subtitles' encoding
+* `pysrt <https://github.com/byroot/pysrt>`_ to validate downloaded subtitles

docs/user/provider_guide.rst

@@ -0,0 +1,96 @@
+Provider Guide
+==============
+This guide is going to explain how to add a :class:`~subliminal.providers.Provider` to subliminal. You are encouraged
+to take a look at the existing providers, it can be a nice base to start your own provider.
+
+
+Requirements
+------------
+When starting a provider you should be able to answer to the following questions:
+
+* What languages does my provider support?
+* What are the language codes for the supported languages?
+* Does my provider deliver subtitles for episodes? for movies?
+* Does my provider require a video hash?
+
+Each response of these questions will help you set the correct attributes for your
+:class:`~subliminal.providers.Provider`.
+
+
+Video Validation
+----------------
+Not all providers deliver subtitles for :class:`~subliminal.video.Episode`. Some may require a hash.
+The :meth:`~subliminal.providers.Provider.check` method does validation against a :class:`~subliminal.video.Video`
+object and will return `False` if the given :class:`~subliminal.video.Video` isn't suitable. If you're not happy
+with the default implementation, you can override it.
+
+
+Configuration
+-------------
+API keys must not be configurable by the user and must remain linked to subliminal. Hence they must be written
+in the provider module.
+
+Per-user authentication is allowed and must be configured at instantiation as keyword arguments. Configuration
+will be done by the user through the `provider_configs` argument of the :func:`~subliminal.core.list_subtitles` and
+:func:`~subliminal.core.download_best_subtitles` functions. No network operation must be done during instantiation,
+only configuration. Any error in the configuration must raise a
+:class:`~subliminal.exceptions.ConfigurationError`.
+
+
+Beyond this point, if an error occurs, a generic :class:`~subliminal.exceptions.ProviderError` exception 
+must be raised. You can also use more explicit exception classes :class:`~subliminal.exceptions.AuthenticationError`
+and :class:`~subliminal.exceptions.DownloadLimitExceeded`.
+
+
+Initialization / Termination
+----------------------------
+Actual authentication operations must take place in the :meth:`~subliminal.providers.Provider.initialize` method.
+If you need anything to be executed when the provider isn't used anymore like logout,
+use :meth:`~subliminal.providers.Provider.terminate`.
+
+
+Caching policy
+--------------
+To save bandwidth and improve querying time, intermediate data should be cached when possible. Typical use case is
+when a query to retrieve show ids is required prior to the query to actually search for subtitles. In that case
+the function that gets the show id from the show name must be cached.
+Expiration time should be :data:`~subliminal.cache.SHOW_EXPIRATION_TIME` for shows and
+:data:`~subliminal.cache.EPISODE_EXPIRATION_TIME` for episodes.
+
+
+Language
+--------
+To be able to handle various language codes, subliminal makes use of `babelfish <http://babelfish.readthedocs.org>`_
+Language and converters. You must set the attribute :attr:`~subliminal.providers.Provider.languages` with a set of
+supported :class:`~babelfish.language.Language`.
+
+If you cannot find a suitable converter for your provider, you can `make one of your own
+<http://babelfish.readthedocs.org/en/latest/#custom-converters>`_.
+
+
+Querying
+--------
+The :meth:`~subliminal.providers.Provider.query` method parameters must include all aspects of provider's querying with
+primary types.
+
+
+Subtitle
+--------
+A custom :class:`~subliminal.subtitle.Subtitle` subclass must be created to represent a subtitle from the provider.
+It must have relevant attributes that can be used to compute the matches of the subtitle against a
+:class:`~subliminal.video.Video` object.
+
+
+Score computation
+-----------------
+To be able to compare subtitles coming from different providers between them, the
+:meth:`~subliminal.subtitle.Subtitle.get_matches` method must be implemented.
+
+
+Unittesting
+-----------
+All possible uses of :meth:`~subliminal.providers.Provider.query`,
+:meth:`~subliminal.providers.Provider.list_subtitles` and :meth:`~subliminal.providers.Provider.download_subtitle`
+methods must have integration tests. Use `vcrpy <https://github.com/kevin1024/vcrpy>`_ for recording and playback
+of network activity.
+Other functions must be unittested. If necessary, you can use :mod:`unittest.mock` to mock some functions.

docs/user/usage.rst

@@ -0,0 +1,148 @@
+Usage
+=====
+CLI
+---
+Download English subtitles::
+
+    $ subliminal download -l en The.Big.Bang.Theory.S05E18.HDTV.x264-LOL.mp4
+    Collecting videos  [####################################]  100%
+    1 video collected / 0 video ignored
+    Downloading subtitles  [####################################]  100%
+    Downloaded 1 subtitle
+
+.. warning::
+
+    For cron usage, make sure to specify a maximum age (with ``--age``) so subtitles are searched for recent videos
+    only. Otherwise you will get banned from the providers for abuse due to too many requests. If subliminal didn't
+    find subtitles for an old video, it's unlikely it will find subtitles for that video ever anyway.
+
+See :ref:`cli` for more details on the available commands and options.
+
+
+Nautilus/Nemo integration
+-------------------------
+See the dedicated `project page <https://github.com/Diaoul/nautilus-subliminal>`_ for more information.
+
+
+High level API
+--------------
+You can call subliminal in many different ways depending on how much control you want over the process. For most use
+cases, you can stick to the standard API.
+
+Common
+^^^^^^
+Let's start by importing subliminal:
+
+    >>> import os
+    >>> from babelfish import *
+    >>> from subliminal import *
+
+Before going further, there are a few things to know about subliminal.
+
+Video
+^^^^^
+The :class:`~subliminal.video.Movie` and :class:`~subliminal.video.Episode` classes represent a video,
+existing or not. You can create a video by name (or path) with :meth:`Video.fromname <subliminal.video.Video.fromname>`,
+use :func:`~subliminal.core.scan_video` on an existing file path to get even more information about the video or
+use :func:`~subliminal.core.scan_videos` on an existing directory path to scan a whole directory for videos.
+
+    >>> video = Video.fromname('The.Big.Bang.Theory.S05E18.HDTV.x264-LOL.mp4')
+    >>> video
+    <Episode ['The Big Bang Theory', 5x18]>
+
+Here video information was guessed based on the name of the video, you can access some video attributes:
+
+    >>> video.video_codec
+    'h264'
+    >>> video.release_group
+    'LOL'
+
+Configuration
+^^^^^^^^^^^^^
+Before proceeding to listing and downloading subtitles, you need to configure the cache. Subliminal uses a cache to
+reduce repeated queries to providers and improve overall performance with no impact on search quality. For the sake
+of this example, we're going to use a memory backend.
+
+    >>> my_region = region.configure('dogpile.cache.memory')
+
+.. warning::
+
+    Choose a cache that fits your application and prefer persistent over volatile backends. The ``file`` backend is
+    usually a good choice.
+    See `dogpile.cache's documentation <http://dogpilecache.readthedocs.org>`_ for more details on backends.
+
+Now that we're done with the basics, let's have some *real* fun.
+
+Listing
+^^^^^^^
+To list subtitles, subliminal provides a :func:`~subliminal.core.list_subtitles` function that will return all found
+subtitles:
+
+    >>> subtitles = list_subtitles([video], {Language('hun')}, providers=['podnapisi'])
+    >>> subtitles[video]
+    [<PodnapisiSubtitle 'ZtAW' [hu]>, <PodnapisiSubtitle 'ONAW' [hu]>]
+
+.. note::
+
+    As you noticed, all parameters are iterables but only contain one item which means you can deal with a lot of
+    videos, languages and providers at the same time. For the sake of this example, we filter providers to use only one,
+    pass ``providers=None`` (default) to search on all providers.
+
+Scoring
+^^^^^^^
+It's usual you have multiple candidates for subtitles. To help you chose which one to download, subliminal can compare
+them to the video and tell you exactly what matches with :meth:`~subliminal.subtitle.Subtitle.get_matches`:
+
+    >>> for s in subtitles[video]:
+    ...     sorted(s.get_matches(video))
+    ['episode', 'format', 'release_group', 'season', 'series', 'video_codec', 'year']
+    ['episode', 'format', 'season', 'series', 'year']
+
+And then compute a score with those matches with :func:`~subliminal.score.compute_score`:
+
+    >>> for s in subtitles[video]:
+    ...     {s: compute_score(s, video)}
+    {<PodnapisiSubtitle 'ZtAW' [hu]>: 354}
+    {<PodnapisiSubtitle 'ONAW' [hu]>: 337}
+
+Now you should have a better idea about which one you should choose.
+
+Downloading
+^^^^^^^^^^^
+We can settle on the first subtitle and download its content using :func:`~subliminal.core.download_subtitles`:
+
+    >>> subtitle = subtitles[video][0]
+    >>> subtitle.content is None
+    True
+    >>> download_subtitles([subtitle])
+    >>> subtitle.content.split(b'\n')[2]
+    b'Elszaladok a boltba'
+
+If you want a string instead of bytes, you can access decoded content with the
+:attr:`~subliminal.subtitle.Subtitle.text` property:
+
+    >>> subtitle.text.split('\n')[3]
+    'néhány apróságért.'
+
+Downloading best subtitles
+^^^^^^^^^^^^^^^^^^^^^^^^^^
+Downloading best subtitles is what you want to do in almost all cases, as a shortcut for listing, scoring and
+downloading you can use :func:`~subliminal.core.download_best_subtitles`:
+
+    >>> best_subtitles = download_best_subtitles([video], {Language('hun')}, providers=['podnapisi'])
+    >>> best_subtitles[video]
+    [<PodnapisiSubtitle 'ZtAW' [hu]>]
+    >>> best_subtitle = best_subtitles[video][0]
+    >>> best_subtitle.content.split(b'\n')[2]
+    b'Elszaladok a boltba'
+
+We end up with the same subtitle but with one line of code. Neat.
+
+Save
+^^^^
+We got ourselves a nice subtitle, now we can save it on the file system using :func:`~subliminal.core.save_subtitles`:
+
+    >>> save_subtitles(video, [best_subtitle])
+    [<PodnapisiSubtitle 'ZtAW' [hu]>]
+    >>> os.listdir()
+    ['The.Big.Bang.Theory.S05E18.HDTV.x264-LOL.hu.srt']

optional-requirements.txt

@@ -1 +0,0 @@
-lxml

pytest.ini

@@ -0,0 +1,11 @@
+[pytest]
+norecursedirs = build dist env .tox .eggs
+addopts = --pep8 --flakes --doctest-glob='*.rst'
+pep8maxlinelength = 120
+pep8ignore =
+    docs/conf.py ALL
+    subliminal/__init__.py E402
+flakes-ignore =
+    docs/conf.py ALL
+    subliminal/__init__.py UnusedImport
+doctest_optionflags = NORMALIZE_WHITESPACE IGNORE_EXCEPTION_DETAIL

requirements.txt

@@ -1,5 +1 @@
-beautifulsoup4>=4.0
-guessit>=0.4.1
-requests
-enzyme>=0.1
-html5lib
+-e .

scripts/subliminal

@@ -1,99 +0,0 @@
-#!/usr/bin/env python
-# -*- coding: utf-8 -*-
-# Copyright 2011-2012 Antoine Bertin <diaoulael@gmail.com>
-#
-# This file is part of subliminal.
-#
-# subliminal is free software; you can redistribute it and/or modify it under
-# the terms of the GNU Lesser General Public License as published by
-# the Free Software Foundation; either version 3 of the License, or
-# (at your option) any later version.
-#
-# subliminal is distributed in the hope that it will be useful,
-# but WITHOUT ANY WARRANTY; without even the implied warranty of
-# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
-# GNU Lesser General Public License for more details.
-#
-# You should have received a copy of the GNU Lesser General Public License
-# along with subliminal.  If not, see <http://www.gnu.org/licenses/>.
-import argparse
-import datetime
-import logging
-import os
-import re
-import subliminal
-import sys
-
-
-def main():
-    parser = argparse.ArgumentParser(description='Subtitles, faster than your thoughts')
-    parser.add_argument('-l', '--language', action='append', dest='languages', help='wanted language (ISO 639-1)', metavar='LG')
-    parser.add_argument('-s', '--service', action='append', dest='services', help='service to use', metavar='NAME')
-    parser.add_argument('-m', '--multi', action='store_true', help='download multiple subtitle languages')
-    parser.add_argument('-f', '--force', action='store_true', help='replace existing subtitle file')
-    parser.add_argument('-w', '--workers', action='store', help='use N threads (default: %(default)s)', metavar='N', type=int, default=4)
-    parser.add_argument('-a', '--age', action='store', help='scan only for files newer or older (prefix with +) than AGE (e.g. 12h, 1w2d, +3d6h)', metavar='AGE', default=None)
-    parser.add_argument('-c', '--compatibility', action='store_true', help='try not to use unicode (use this if you have encoding errors)')
-    group_verbosity = parser.add_mutually_exclusive_group()
-    group_verbosity.add_argument('-q', '--quiet', action='store_true', help='disable output')
-    group_verbosity.add_argument('-v', '--verbose', action='store_true', help='verbose output')
-    group_cache = parser.add_mutually_exclusive_group()
-    group_cache.add_argument('--cache-dir', action='store', dest='cache_dir', help='cache directory to use', metavar='DIR', default=os.path.expanduser('~/.config/subliminal'))
-    group_cache.add_argument('--no-cache-dir', action='store_false', dest='cache_dir', help='do not use cache directory (some services may not work)')
-    parser.add_argument('--version', action='version', version=subliminal.__version__)
-    parser.add_argument('paths', nargs='+', help='path to video file or folder', metavar='PATH')
-    args = parser.parse_args()
-
-    # Set log verbosity
-    if args.verbose:
-        logging.basicConfig(level=logging.DEBUG, format='%(levelname)-8s %(asctime)s %(name)-24s %(message)s', datefmt='%Y-%m-%d %H:%M:%S')
-    elif not args.quiet:
-        logging.basicConfig(level=logging.WARN, format='%(levelname)s: %(name)s %(message)s')
-
-    # Create cache directory
-    if not os.path.exists(args.cache_dir):
-        os.mkdir(args.cache_dir)
-
-    # Create filter function
-    scan_filter = None
-    if args.age:
-        regex = re.compile(r'^(?P<sign>\+?)((?P<weeks>\d+?)w)?((?P<days>\d+?)d)?((?P<hours>\d+?)h)?')
-        parts = regex.match(args.age)
-        if not parts:
-            raise ValueError('Incorrect age format')
-        time_params = {}
-        parts = parts.groupdict()
-        for name, param in parts.iteritems():
-            if param and name != 'sign':
-                time_params[name] = int(param)
-        if parts['sign'] == '+':
-            scan_filter = lambda x: datetime.datetime.now() - datetime.datetime.fromtimestamp(os.path.getmtime(x)) < datetime.timedelta(**time_params)
-        else:
-            scan_filter = lambda x: datetime.datetime.now() - datetime.datetime.fromtimestamp(os.path.getmtime(x)) > datetime.timedelta(**time_params)
-
-    # Compatibility mode
-    if args.compatibility:
-        paths = args.paths
-    else:
-        paths = [unicode(x) for x in args.paths]
-
-    # Download subtitles
-    with subliminal.Pool(args.workers) as p:
-        results = p.download_subtitles(paths, languages=args.languages, services=args.services, cache_dir=args.cache_dir,
-                                       force=args.force, multi=args.multi, scan_filter=scan_filter)
-
-    if not results:
-        if not args.quiet:
-            sys.stderr.write('No subtitles downloaded\n')
-        exit(1)
-    if not args.quiet:
-        print '*' * 50
-        print 'Downloaded %d subtitle(s) for %d video(s)' % (sum([len(s) for s in results.itervalues()]), len(results))
-        for _, subtitles in results.iteritems():
-            for subtitle in subtitles:
-                print '%s from %s' % (subtitle.path, subtitle.service)
-        print '*' * 50
-
-
-if __name__ == '__main__':
-    main()

setup.cfg

@@ -1,3 +1,6 @@
+[aliases]
+test=pytest
+
 [build_sphinx]
 source-dir = docs/
 build-dir  = docs/_build

setup.py

@@ -1,53 +1,101 @@
 #!/usr/bin/env python
 # -*- coding: utf-8 -*-
-# Copyright 2011-2012 Antoine Bertin <diaoulael@gmail.com>
-#
-# This file is part of subliminal.
-#
-# subliminal is free software; you can redistribute it and/or modify it under
-# the terms of the GNU Lesser General Public License as published by
-# the Free Software Foundation; either version 3 of the License, or
-# (at your option) any later version.
-#
-# subliminal is distributed in the hope that it will be useful,
-# but WITHOUT ANY WARRANTY; without even the implied warranty of
-# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
-# GNU Lesser General Public License for more details.
-#
-# You should have received a copy of the GNU Lesser General Public License
-# along with subliminal.  If not, see <http://www.gnu.org/licenses/>.
-import os.path
+import io
+import os
+import re
 import sys
+
 from setuptools import setup, find_packages
 
+here = os.path.abspath(os.path.dirname(__file__))
 
-def read(fname):
-    return open(os.path.join(os.path.dirname(__file__), fname)).read()
 
-required = ['beautifulsoup4 >= 4.0', 'guessit >= 0.4.1', 'requests', 'enzyme >= 0.1', 'html5lib']
-if sys.hexversion < 0x20700f0:
-    required.append('argparse >= 1.1')
+def read(*parts):
+    # intentionally *not* adding an encoding option to open, See:
+    #   https://github.com/pypa/virtualenv/issues/201#issuecomment-3145690
+    return io.open(os.path.join(here, *parts), 'r').read()
+
+
+def find_version(*file_paths):
+    version_file = read(*file_paths)
+    version_match = re.search(r'^__version__ = [\'"]([^\'"]*)[\'"]', version_file, re.M)
+    if version_match:
+        return version_match.group(1)
+    raise RuntimeError('Unable to find version string.')
+
+
+# requirements
+setup_requirements = ['pytest-runner'] if {'pytest', 'test', 'ptr'}.intersection(sys.argv) else []
+
+install_requirements = ['guessit>=2.0.1', 'babelfish>=0.5.2', 'enzyme>=0.4.1', 'beautifulsoup4>=4.4.0',
+                        'requests>=2.0', 'click>=4.0', 'dogpile.cache>=0.6.0', 'stevedore>=1.0.0',
+                        'chardet>=2.3.0', 'pysrt>=1.0.1', 'six>=1.9.0', 'appdirs>=1.3', 'rarfile>=2.7',
+                        'pytz>=2012c']
+if sys.version_info < (3, 2):
+    install_requirements.append('futures>=3.0')
+
+test_requirements = ['sympy', 'vcrpy>=1.6.1', 'pytest', 'pytest-pep8', 'pytest-flakes', 'pytest-cov']
+if sys.version_info < (3, 3):
+    test_requirements.append('mock')
+
+dev_requirements = ['tox', 'sphinx', 'sphinx_rtd_theme', 'sphinxcontrib-programoutput', 'wheel']
+
 
-execfile(os.path.join(os.path.dirname(__file__), 'subliminal', 'infos.py'))
 setup(name='subliminal',
-    version=__version__,
-    license='LGPLv3',
-    description='Subtitles, faster than your thoughts',
-    long_description=read('README.rst') + '\n\n' + read('NEWS.rst'),
-    classifiers=['Development Status :: 4 - Beta',
-        'License :: OSI Approved :: GNU Library or Lesser General Public License (LGPL)',
-        'Intended Audience :: Developers',
-        'Operating System :: OS Independent',
-        'Programming Language :: Python :: 2.6',
-        'Programming Language :: Python :: 2.7',
-        'Topic :: Software Development :: Libraries :: Python Modules',
-        'Topic :: Multimedia :: Video'],
-    keywords='subtitle subtitles video movie episode tv show',
-    author='Antoine Bertin',
-    author_email='diaoulael@gmail.com',
-    url='https://github.com/Diaoul/subliminal',
-    packages=find_packages(),
-    scripts=['scripts/subliminal'],
-    test_suite='tests.suite',
-    install_requires=required,
-    extras_require={'full': ['lxml']})
+      version=find_version('subliminal', '__init__.py'),
+      license='MIT',
+      description='Subtitles, faster than your thoughts',
+      long_description=read('README.rst') + '\n\n' + read('HISTORY.rst'),
+      keywords='subtitle subtitles video movie episode tv show series',
+      url='https://github.com/Diaoul/subliminal',
+      author='Antoine Bertin',
+      author_email='diaoulael@gmail.com',
+      packages=find_packages(),
+      classifiers=[
+          'Development Status :: 5 - Production/Stable',
+          'Intended Audience :: Developers',
+          'License :: OSI Approved :: MIT License',
+          'Operating System :: OS Independent',
+          'Programming Language :: Python',
+          'Programming Language :: Python :: 2',
+          'Programming Language :: Python :: 2.7',
+          'Programming Language :: Python :: 3',
+          'Programming Language :: Python :: 3.3',
+          'Programming Language :: Python :: 3.4',
+          'Programming Language :: Python :: 3.5',
+          'Topic :: Software Development :: Libraries :: Python Modules',
+          'Topic :: Multimedia :: Video'
+      ],
+      entry_points={
+          'subliminal.providers': [
+              'addic7ed = subliminal.providers.addic7ed:Addic7edProvider',
+              'legendastv = subliminal.providers.legendastv:LegendasTVProvider',
+              'opensubtitles = subliminal.providers.opensubtitles:OpenSubtitlesProvider',
+              'podnapisi = subliminal.providers.podnapisi:PodnapisiProvider',
+              'shooter = subliminal.providers.shooter:ShooterProvider',
+              'subscenter = subliminal.providers.subscenter:SubsCenterProvider',
+              'thesubdb = subliminal.providers.thesubdb:TheSubDBProvider',
+              'tvsubtitles = subliminal.providers.tvsubtitles:TVsubtitlesProvider'
+          ],
+          'subliminal.refiners': [
+              'metadata = subliminal.refiners.metadata:refine',
+              'omdb = subliminal.refiners.omdb:refine',
+              'tvdb = subliminal.refiners.tvdb:refine'
+          ],
+          'babelfish.language_converters': [
+              'addic7ed = subliminal.converters.addic7ed:Addic7edConverter',
+              'shooter = subliminal.converters.shooter:ShooterConverter',
+              'thesubdb = subliminal.converters.thesubdb:TheSubDBConverter',
+              'tvsubtitles = subliminal.converters.tvsubtitles:TVsubtitlesConverter'
+          ],
+          'console_scripts': [
+              'subliminal = subliminal.cli:subliminal'
+          ]
+      },
+      setup_requires=setup_requirements,
+      install_requires=install_requirements,
+      tests_require=test_requirements,
+      extras_require={
+          'test': test_requirements,
+          'dev': dev_requirements
+      })

subliminal/__init__.py

@@ -1,34 +1,21 @@
 # -*- coding: utf-8 -*-
-# Copyright 2011-2012 Antoine Bertin <diaoulael@gmail.com>
-#
-# This file is part of subliminal.
-#
-# subliminal is free software; you can redistribute it and/or modify it under
-# the terms of the GNU Lesser General Public License as published by
-# the Free Software Foundation; either version 3 of the License, or
-# (at your option) any later version.
-#
-# subliminal is distributed in the hope that it will be useful,
-# but WITHOUT ANY WARRANTY; without even the implied warranty of
-# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
-# GNU Lesser General Public License for more details.
-#
-# You should have received a copy of the GNU Lesser General Public License
-# along with subliminal.  If not, see <http://www.gnu.org/licenses/>.
-from .api import list_subtitles, download_subtitles
-from .async import Pool
-from .core import (SERVICES, LANGUAGE_INDEX, SERVICE_INDEX, SERVICE_CONFIDENCE,
-    MATCHING_CONFIDENCE)
-from .infos import __version__
+__title__ = 'subliminal'
+__version__ = '2.0.3'
+__short_version__ = '.'.join(__version__.split('.')[:2])
+__author__ = 'Antoine Bertin'
+__license__ = 'MIT'
+__copyright__ = 'Copyright 2016, Antoine Bertin'
+
 import logging
-try:
-    from logging import NullHandler
-except ImportError:
-    class NullHandler(logging.Handler):
-        def emit(self, record):
-            pass
 
+from .core import (AsyncProviderPool, ProviderPool, check_video, download_best_subtitles, download_subtitles,
+                   list_subtitles, refine, save_subtitles, scan_video, scan_videos)
+from .cache import region
+from .exceptions import Error, ProviderError
+from .extensions import provider_manager, refiner_manager
+from .providers import Provider
+from .score import compute_score, get_scores
+from .subtitle import SUBTITLE_EXTENSIONS, Subtitle
+from .video import VIDEO_EXTENSIONS, Episode, Movie, Video
 
-__all__ = ['SERVICES', 'LANGUAGE_INDEX', 'SERVICE_INDEX', 'SERVICE_CONFIDENCE',
-           'MATCHING_CONFIDENCE', 'list_subtitles', 'download_subtitles', 'Pool']
-logging.getLogger(__name__).addHandler(NullHandler())
+logging.getLogger(__name__).addHandler(logging.NullHandler())

subliminal/api.py

@@ -1,109 +0,0 @@
-# -*- coding: utf-8 -*-
-# Copyright 2011-2012 Antoine Bertin <diaoulael@gmail.com>
-#
-# This file is part of subliminal.
-#
-# subliminal is free software; you can redistribute it and/or modify it under
-# the terms of the GNU Lesser General Public License as published by
-# the Free Software Foundation; either version 3 of the License, or
-# (at your option) any later version.
-#
-# subliminal is distributed in the hope that it will be useful,
-# but WITHOUT ANY WARRANTY; without even the implied warranty of
-# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
-# GNU Lesser General Public License for more details.
-#
-# You should have received a copy of the GNU Lesser General Public License
-# along with subliminal.  If not, see <http://www.gnu.org/licenses/>.
-from .core import (SERVICES, LANGUAGE_INDEX, SERVICE_INDEX, SERVICE_CONFIDENCE,
-    MATCHING_CONFIDENCE, create_list_tasks, consume_task, create_download_tasks,
-    group_by_video, key_subtitles)
-from .language import language_set, language_list, LANGUAGES
-import logging
-
-
-__all__ = ['list_subtitles', 'download_subtitles']
-logger = logging.getLogger(__name__)
-
-
-def list_subtitles(paths, languages=None, services=None, force=True, multi=False, cache_dir=None, max_depth=3, scan_filter=None):
-    """List subtitles in given paths according to the criteria
-
-    :param paths: path(s) to video file or folder
-    :type paths: string or list
-    :param languages: languages to search for, in preferred order
-    :type languages: list of :class:`~subliminal.language.Language` or string
-    :param list services: services to use for the search, in preferred order
-    :param bool force: force searching for subtitles even if some are detected
-    :param bool multi: search multiple languages for the same video
-    :param string cache_dir: path to the cache directory to use
-    :param int max_depth: maximum depth for scanning entries
-    :param function scan_filter: filter function that takes a path as argument and returns a boolean indicating whether it has to be filtered out (``True``) or not (``False``)
-    :return: found subtitles
-    :rtype: dict of :class:`~subliminal.videos.Video` => [:class:`~subliminal.subtitles.ResultSubtitle`]
-
-    """
-    services = services or SERVICES
-    languages = language_set(languages) if languages is not None else language_set(LANGUAGES)
-    if isinstance(paths, basestring):
-        paths = [paths]
-    if any([not isinstance(p, unicode) for p in paths]):
-        logger.warning(u'Not all entries are unicode')
-    results = []
-    service_instances = {}
-    tasks = create_list_tasks(paths, languages, services, force, multi, cache_dir, max_depth, scan_filter)
-    for task in tasks:
-        try:
-            result = consume_task(task, service_instances)
-            results.append((task.video, result))
-        except:
-            logger.error(u'Error consuming task %r' % task, exc_info=True)
-    for service_instance in service_instances.itervalues():
-        service_instance.terminate()
-    return group_by_video(results)
-
-
-def download_subtitles(paths, languages=None, services=None, force=True, multi=False, cache_dir=None, max_depth=3, scan_filter=None, order=None):
-    """Download subtitles in given paths according to the criteria
-
-    :param paths: path(s) to video file or folder
-    :type paths: string or list
-    :param languages: languages to search for, in preferred order
-    :type languages: list of :class:`~subliminal.language.Language` or string
-    :param list services: services to use for the search, in preferred order
-    :param bool force: force searching for subtitles even if some are detected
-    :param bool multi: search multiple languages for the same video
-    :param string cache_dir: path to the cache directory to use
-    :param int max_depth: maximum depth for scanning entries
-    :param function scan_filter: filter function that takes a path as argument and returns a boolean indicating whether it has to be filtered out (``True``) or not (``False``)
-    :param order: preferred order for subtitles sorting
-    :type list: list of :data:`~subliminal.core.LANGUAGE_INDEX`, :data:`~subliminal.core.SERVICE_INDEX`, :data:`~subliminal.core.SERVICE_CONFIDENCE`, :data:`~subliminal.core.MATCHING_CONFIDENCE`
-    :return: downloaded subtitles
-    :rtype: dict of :class:`~subliminal.videos.Video` => [:class:`~subliminal.subtitles.ResultSubtitle`]
-
-    .. note::
-
-        If you use ``multi=True``, :data:`~subliminal.core.LANGUAGE_INDEX` has to be the first item of the ``order`` list
-        or you might get unexpected results.
-
-    """
-    services = services or SERVICES
-    languages = language_list(languages) if languages is not None else language_list(LANGUAGES)
-    if isinstance(paths, basestring):
-        paths = [paths]
-    order = order or [LANGUAGE_INDEX, SERVICE_INDEX, SERVICE_CONFIDENCE, MATCHING_CONFIDENCE]
-    subtitles_by_video = list_subtitles(paths, languages, services, force, multi, cache_dir, max_depth, scan_filter)
-    for video, subtitles in subtitles_by_video.iteritems():
-        subtitles.sort(key=lambda s: key_subtitles(s, video, languages, services, order), reverse=True)
-    results = []
-    service_instances = {}
-    tasks = create_download_tasks(subtitles_by_video, languages, multi)
-    for task in tasks:
-        try:
-            result = consume_task(task, service_instances)
-            results.append((task.video, result))
-        except:
-            logger.error(u'Error consuming task %r' % task, exc_info=True)
-    for service_instance in service_instances.itervalues():
-        service_instance.terminate()
-    return group_by_video(results)

subliminal/async.py

@@ -1,142 +0,0 @@
-# -*- coding: utf-8 -*-
-# Copyright 2011-2012 Antoine Bertin <diaoulael@gmail.com>
-#
-# This file is part of subliminal.
-#
-# subliminal is free software; you can redistribute it and/or modify it under
-# the terms of the GNU Lesser General Public License as published by
-# the Free Software Foundation; either version 3 of the License, or
-# (at your option) any later version.
-#
-# subliminal is distributed in the hope that it will be useful,
-# but WITHOUT ANY WARRANTY; without even the implied warranty of
-# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
-# GNU Lesser General Public License for more details.
-#
-# You should have received a copy of the GNU Lesser General Public License
-# along with subliminal.  If not, see <http://www.gnu.org/licenses/>.
-from .core import (consume_task, LANGUAGE_INDEX, SERVICE_INDEX,
-    SERVICE_CONFIDENCE, MATCHING_CONFIDENCE, SERVICES, create_list_tasks,
-    create_download_tasks, group_by_video, key_subtitles)
-from .language import language_list, language_set, LANGUAGES
-from .tasks import StopTask
-import Queue
-import logging
-import threading
-
-
-__all__ = ['Worker', 'Pool']
-logger = logging.getLogger(__name__)
-
-
-class Worker(threading.Thread):
-    """Consume tasks and put the result in the queue"""
-    def __init__(self, tasks, results):
-        super(Worker, self).__init__()
-        self.tasks = tasks
-        self.results = results
-        self.services = {}
-
-    def run(self):
-        while 1:
-            result = []
-            try:
-                task = self.tasks.get(block=True)
-                if isinstance(task, StopTask):
-                    break
-                result = consume_task(task, self.services)
-                self.results.put((task.video, result))
-            except:
-                logger.error(u'Exception raised in worker %s' % self.name, exc_info=True)
-            finally:
-                self.tasks.task_done()
-        self.terminate()
-        logger.debug(u'Thread %s terminated' % self.name)
-
-    def terminate(self):
-        """Terminate instantiated services"""
-        for service_name, service in self.services.iteritems():
-            try:
-                service.terminate()
-            except:
-                logger.error(u'Exception raised when terminating service %s' % service_name, exc_info=True)
-
-
-class Pool(object):
-    """Pool of workers"""
-    def __init__(self, size):
-        self.tasks = Queue.Queue()
-        self.results = Queue.Queue()
-        self.workers = []
-        for _ in range(size):
-            self.workers.append(Worker(self.tasks, self.results))
-
-    def __enter__(self):
-        self.start()
-        return self
-
-    def __exit__(self, *args):
-        self.stop()
-        self.join()
-
-    def start(self):
-        """Start workers"""
-        for worker in self.workers:
-            worker.start()
-
-    def stop(self):
-        """Stop workers"""
-        for _ in self.workers:
-            self.tasks.put(StopTask())
-
-    def join(self):
-        """Join the task queue"""
-        self.tasks.join()
-
-    def collect(self):
-        """Collect available results
-
-        :return: results of tasks
-        :rtype: list of :class:`~subliminal.tasks.Task`
-
-        """
-        results = []
-        while 1:
-            try:
-                result = self.results.get(block=False)
-                results.append(result)
-            except Queue.Empty:
-                break
-        return results
-
-    def list_subtitles(self, paths, languages=None, services=None, force=True, multi=False, cache_dir=None, max_depth=3, scan_filter=None):
-        """See :meth:`subliminal.list_subtitles`"""
-        services = services or SERVICES
-        languages = language_set(languages) if languages is not None else language_set(LANGUAGES)
-        if isinstance(paths, basestring):
-            paths = [paths]
-        if any([not isinstance(p, unicode) for p in paths]):
-            logger.warning(u'Not all entries are unicode')
-        tasks = create_list_tasks(paths, languages, services, force, multi, cache_dir, max_depth, scan_filter)
-        for task in tasks:
-            self.tasks.put(task)
-        self.join()
-        results = self.collect()
-        return group_by_video(results)
-
-    def download_subtitles(self, paths, languages=None, services=None, force=True, multi=False, cache_dir=None, max_depth=3, scan_filter=None, order=None):
-        """See :meth:`subliminal.download_subtitles`"""
-        services = services or SERVICES
-        languages = language_list(languages) if languages is not None else language_list(LANGUAGES)
-        if isinstance(paths, basestring):
-            paths = [paths]
-        order = order or [LANGUAGE_INDEX, SERVICE_INDEX, SERVICE_CONFIDENCE, MATCHING_CONFIDENCE]
-        subtitles_by_video = self.list_subtitles(paths, languages, services, force, multi, cache_dir, max_depth, scan_filter)
-        for video, subtitles in subtitles_by_video.iteritems():
-            subtitles.sort(key=lambda s: key_subtitles(s, video, languages, services, order), reverse=True)
-        tasks = create_download_tasks(subtitles_by_video, languages, multi)
-        for task in tasks:
-            self.tasks.put(task)
-        self.join()
-        results = self.collect()
-        return group_by_video(results)

subliminal/cache.py

@@ -1,134 +1,16 @@
 # -*- coding: utf-8 -*-
-# Copyright 2012 Nicolas Wack <wackou@gmail.com>
-#
-# This file is part of subliminal.
-#
-# subliminal is free software; you can redistribute it and/or modify it under
-# the terms of the GNU Lesser General Public License as published by
-# the Free Software Foundation; either version 3 of the License, or
-# (at your option) any later version.
-#
-# subliminal is distributed in the hope that it will be useful,
-# but WITHOUT ANY WARRANTY; without even the implied warranty of
-# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
-# GNU Lesser General Public License for more details.
-#
-# You should have received a copy of the GNU Lesser General Public License
-# along with subliminal.  If not, see <http://www.gnu.org/licenses/>.
-from collections import defaultdict
-from functools import wraps
-import logging
-import os.path
-import threading
-try:
-    import cPickle as pickle
-except ImportError:
-    import pickle
+import datetime
+
+from dogpile.cache import make_region
+
+#: Expiration time for show caching
+SHOW_EXPIRATION_TIME = datetime.timedelta(weeks=3).total_seconds()
+
+#: Expiration time for episode caching
+EPISODE_EXPIRATION_TIME = datetime.timedelta(days=3).total_seconds()
+
+#: Expiration time for scraper searches
+REFINER_EXPIRATION_TIME = datetime.timedelta(weeks=1).total_seconds()
 
 
-__all__ = ['Cache', 'cachedmethod']
-logger = logging.getLogger(__name__)
-
-
-class Cache(object):
-    """A Cache object contains cached values for methods. It can have
-    separate internal caches, one for each service
-
-    """
-    def __init__(self, cache_dir):
-        self.cache_dir = cache_dir
-        self.cache = defaultdict(dict)
-        self.lock = threading.RLock()
-
-    def __del__(self):
-        for service_name in self.cache:
-            self.save(service_name)
-
-    def cache_location(self, service_name):
-        return os.path.join(self.cache_dir, 'subliminal_%s.cache' % service_name)
-
-    def load(self, service_name):
-        with self.lock:
-            if service_name in self.cache:
-                # already loaded
-                return
-
-            self.cache[service_name] = defaultdict(dict)
-            filename = self.cache_location(service_name)
-            logger.debug(u'Cache: loading cache from %s' % filename)
-            try:
-                self.cache[service_name] = pickle.load(open(filename, 'rb'))
-            except IOError:
-                logger.info('Cache: Cache file "%s" doesn\'t exist, creating it' % filename)
-            except EOFError:
-                logger.error('Cache: cache file "%s" is corrupted... Removing it.' % filename)
-                os.remove(filename)
-
-    def save(self, service_name):
-        filename = self.cache_location(service_name)
-        logger.debug(u'Cache: saving cache to %s' % filename)
-        with self.lock:
-            pickle.dump(self.cache[service_name], open(filename, 'wb'))
-
-    def clear(self, service_name):
-        try:
-            os.remove(self.cache_location(service_name))
-        except OSError:
-            pass
-        self.cache[service_name] = defaultdict(dict)
-
-    def cached_func_key(self, func, cls=None):
-        try:
-            cls = func.im_class
-        except:
-            pass
-        return ('%s.%s' % (cls.__module__, cls.__name__), func.__name__)
-
-    def function_cache(self, service_name, func):
-        func_key = self.cached_func_key(func)
-        return self.cache[service_name][func_key]
-
-    def cache_for(self, service_name, func, args, result):
-        # no need to lock here, dict ops are atomic
-        self.function_cache(service_name, func)[args] = result
-
-    def cached_value(self, service_name, func, args):
-        """Raises KeyError if not found"""
-        # no need to lock here, dict ops are atomic
-        return self.function_cache(service_name, func)[args]
-
-
-def cachedmethod(function):
-    """Decorator to make a method use the cache.
-
-    .. note::
-
-        This can NOT be used with static functions, it has to be used on
-        methods of some class
-
-    """
-    @wraps(function)
-    def cached(*args):
-        c = args[0].config.cache
-        service_name = args[0].__class__.__name__
-        func_key = c.cached_func_key(function, cls=args[0].__class__)
-        func_cache = c.cache[service_name][func_key]
-
-        # we need to remove the first element of args for the key, as it is the
-        # instance pointer and we don't want the cache to know which instance
-        # called it, it is shared among all instances of the same class
-        key = args[1:]
-
-        if key in func_cache:
-            result = func_cache[key]
-            logger.debug(u'Using cached value for %s(%s), returns: %s' % (func_key, key, result))
-            return result
-
-        result = function(*args)
-
-        # note: another thread could have already cached a value in the
-        # meantime, but that's ok as we prefer to keep the latest value in
-        # the cache
-        func_cache[key] = result
-        return result
-    return cached
+region = make_region()

subliminal/cli.py

@@ -0,0 +1,461 @@
+# -*- coding: utf-8 -*-
+"""
+Subliminal uses `click <http://click.pocoo.org>`_ to provide a powerful :abbr:`CLI (command-line interface)`.
+
+"""
+from __future__ import division
+from collections import defaultdict
+from datetime import timedelta
+import glob
+import json
+import logging
+import os
+import re
+
+from appdirs import AppDirs
+from babelfish import Error as BabelfishError, Language
+import click
+from dogpile.cache.backends.file import AbstractFileLock
+from dogpile.util.readwrite_lock import ReadWriteMutex
+from six.moves import configparser
+
+from subliminal import (AsyncProviderPool, Episode, Movie, Video, __version__, check_video, compute_score, get_scores,
+                        provider_manager, refine, refiner_manager, region, save_subtitles, scan_video, scan_videos)
+from subliminal.core import ARCHIVE_EXTENSIONS, search_external_subtitles
+
+logger = logging.getLogger(__name__)
+
+
+class MutexLock(AbstractFileLock):
+    """:class:`MutexLock` is a thread-based rw lock based on :class:`dogpile.core.ReadWriteMutex`."""
+    def __init__(self, filename):
+        self.mutex = ReadWriteMutex()
+
+    def acquire_read_lock(self, wait):
+        ret = self.mutex.acquire_read_lock(wait)
+        return wait or ret
+
+    def acquire_write_lock(self, wait):
+        ret = self.mutex.acquire_write_lock(wait)
+        return wait or ret
+
+    def release_read_lock(self):
+        return self.mutex.release_read_lock()
+
+    def release_write_lock(self):
+        return self.mutex.release_write_lock()
+
+
+class Config(object):
+    """A :class:`~configparser.ConfigParser` wrapper to store configuration.
+
+    Interaction with the configuration is done with the properties.
+
+    :param str path: path to the configuration file.
+
+    """
+    def __init__(self, path):
+        #: Path to the configuration file
+        self.path = path
+
+        #: The underlying configuration object
+        self.config = configparser.SafeConfigParser()
+        self.config.add_section('general')
+        self.config.set('general', 'languages', json.dumps(['en']))
+        self.config.set('general', 'providers', json.dumps(sorted([p.name for p in provider_manager])))
+        self.config.set('general', 'refiners', json.dumps(sorted([r.name for r in refiner_manager])))
+        self.config.set('general', 'single', str(0))
+        self.config.set('general', 'embedded_subtitles', str(1))
+        self.config.set('general', 'age', str(int(timedelta(weeks=2).total_seconds())))
+        self.config.set('general', 'hearing_impaired', str(1))
+        self.config.set('general', 'min_score', str(0))
+
+    def read(self):
+        """Read the configuration from :attr:`path`"""
+        self.config.read(self.path)
+
+    def write(self):
+        """Write the configuration to :attr:`path`"""
+        with open(self.path, 'w') as f:
+            self.config.write(f)
+
+    @property
+    def languages(self):
+        return {Language.fromietf(l) for l in json.loads(self.config.get('general', 'languages'))}
+
+    @languages.setter
+    def languages(self, value):
+        self.config.set('general', 'languages', json.dumps(sorted([str(l) for l in value])))
+
+    @property
+    def providers(self):
+        return json.loads(self.config.get('general', 'providers'))
+
+    @providers.setter
+    def providers(self, value):
+        self.config.set('general', 'providers', json.dumps(sorted([p.lower() for p in value])))
+
+    @property
+    def refiners(self):
+        return json.loads(self.config.get('general', 'refiners'))
+
+    @refiners.setter
+    def refiners(self, value):
+        self.config.set('general', 'refiners', json.dumps([r.lower() for r in value]))
+
+    @property
+    def single(self):
+        return self.config.getboolean('general', 'single')
+
+    @single.setter
+    def single(self, value):
+        self.config.set('general', 'single', str(int(value)))
+
+    @property
+    def embedded_subtitles(self):
+        return self.config.getboolean('general', 'embedded_subtitles')
+
+    @embedded_subtitles.setter
+    def embedded_subtitles(self, value):
+        self.config.set('general', 'embedded_subtitles', str(int(value)))
+
+    @property
+    def age(self):
+        return timedelta(seconds=self.config.getint('general', 'age'))
+
+    @age.setter
+    def age(self, value):
+        self.config.set('general', 'age', str(int(value.total_seconds())))
+
+    @property
+    def hearing_impaired(self):
+        return self.config.getboolean('general', 'hearing_impaired')
+
+    @hearing_impaired.setter
+    def hearing_impaired(self, value):
+        self.config.set('general', 'hearing_impaired', str(int(value)))
+
+    @property
+    def min_score(self):
+        return self.config.getfloat('general', 'min_score')
+
+    @min_score.setter
+    def min_score(self, value):
+        self.config.set('general', 'min_score', str(value))
+
+    @property
+    def provider_configs(self):
+        rv = {}
+        for provider in provider_manager:
+            if self.config.has_section(provider.name):
+                rv[provider.name] = {k: v for k, v in self.config.items(provider.name)}
+        return rv
+
+    @provider_configs.setter
+    def provider_configs(self, value):
+        # loop over provider configurations
+        for provider, config in value.items():
+            # create the corresponding section if necessary
+            if not self.config.has_section(provider):
+                self.config.add_section(provider)
+
+            # add config options
+            for k, v in config.items():
+                self.config.set(provider, k, v)
+
+
+class LanguageParamType(click.ParamType):
+    """:class:`~click.ParamType` for languages that returns a :class:`~babelfish.language.Language`"""
+    name = 'language'
+
+    def convert(self, value, param, ctx):
+        try:
+            return Language.fromietf(value)
+        except BabelfishError:
+            self.fail('%s is not a valid language' % value)
+
+LANGUAGE = LanguageParamType()
+
+
+class AgeParamType(click.ParamType):
+    """:class:`~click.ParamType` for age strings that returns a :class:`~datetime.timedelta`
+
+    An age string is in the form `number + identifier` with possible identifiers:
+
+        * ``w`` for weeks
+        * ``d`` for days
+        * ``h`` for hours
+
+    The form can be specified multiple times but only with that idenfier ordering. For example:
+
+        * ``1w2d4h`` for 1 week, 2 days and 4 hours
+        * ``2w`` for 2 weeks
+        * ``3w6h`` for 3 weeks and 6 hours
+
+    """
+    name = 'age'
+
+    def convert(self, value, param, ctx):
+        match = re.match(r'^(?:(?P<weeks>\d+?)w)?(?:(?P<days>\d+?)d)?(?:(?P<hours>\d+?)h)?$', value)
+        if not match:
+            self.fail('%s is not a valid age' % value)
+
+        return timedelta(**{k: int(v) for k, v in match.groupdict(0).items()})
+
+AGE = AgeParamType()
+
+PROVIDER = click.Choice(sorted(provider_manager.names()))
+
+REFINER = click.Choice(sorted(refiner_manager.names()))
+
+dirs = AppDirs('subliminal')
+cache_file = 'subliminal.dbm'
+config_file = 'config.ini'
+
+
+@click.group(context_settings={'max_content_width': 100}, epilog='Suggestions and bug reports are greatly appreciated: '
+             'https://github.com/Diaoul/subliminal/')
+@click.option('--addic7ed', type=click.STRING, nargs=2, metavar='USERNAME PASSWORD', help='Addic7ed configuration.')
+@click.option('--legendastv', type=click.STRING, nargs=2, metavar='USERNAME PASSWORD', help='LegendasTV configuration.')
+@click.option('--opensubtitles', type=click.STRING, nargs=2, metavar='USERNAME PASSWORD',
+              help='OpenSubtitles configuration.')
+@click.option('--subscenter', type=click.STRING, nargs=2, metavar='USERNAME PASSWORD', help='SubsCenter configuration.')
+@click.option('--cache-dir', type=click.Path(writable=True, file_okay=False), default=dirs.user_cache_dir,
+              show_default=True, expose_value=True, help='Path to the cache directory.')
+@click.option('--debug', is_flag=True, help='Print useful information for debugging subliminal and for reporting bugs.')
+@click.version_option(__version__)
+@click.pass_context
+def subliminal(ctx, addic7ed, legendastv, opensubtitles, subscenter, cache_dir, debug):
+    """Subtitles, faster than your thoughts."""
+    # create cache directory
+    try:
+        os.makedirs(cache_dir)
+    except OSError:
+        if not os.path.isdir(cache_dir):
+            raise
+
+    # configure cache
+    region.configure('dogpile.cache.dbm', expiration_time=timedelta(days=30),
+                     arguments={'filename': os.path.join(cache_dir, cache_file), 'lock_factory': MutexLock})
+
+    # configure logging
+    if debug:
+        handler = logging.StreamHandler()
+        handler.setFormatter(logging.Formatter(logging.BASIC_FORMAT))
+        logging.getLogger('subliminal').addHandler(handler)
+        logging.getLogger('subliminal').setLevel(logging.DEBUG)
+
+    # provider configs
+    ctx.obj = {'provider_configs': {}}
+    if addic7ed:
+        ctx.obj['provider_configs']['addic7ed'] = {'username': addic7ed[0], 'password': addic7ed[1]}
+    if legendastv:
+        ctx.obj['provider_configs']['legendastv'] = {'username': legendastv[0], 'password': legendastv[1]}
+    if opensubtitles:
+        ctx.obj['provider_configs']['opensubtitles'] = {'username': opensubtitles[0], 'password': opensubtitles[1]}
+    if subscenter:
+        ctx.obj['provider_configs']['subscenter'] = {'username': subscenter[0], 'password': subscenter[1]}
+
+
+@subliminal.command()
+@click.option('--clear-subliminal', is_flag=True, help='Clear subliminal\'s cache. Use this ONLY if your cache is '
+              'corrupted or if you experience issues.')
+@click.pass_context
+def cache(ctx, clear_subliminal):
+    """Cache management."""
+    if clear_subliminal:
+        for file in glob.glob(os.path.join(ctx.parent.params['cache_dir'], cache_file) + '*'):
+            os.remove(file)
+        click.echo('Subliminal\'s cache cleared.')
+    else:
+        click.echo('Nothing done.')
+
+
+@subliminal.command()
+@click.option('-l', '--language', type=LANGUAGE, required=True, multiple=True, help='Language as IETF code, '
+              'e.g. en, pt-BR (can be used multiple times).')
+@click.option('-p', '--provider', type=PROVIDER, multiple=True, help='Provider to use (can be used multiple times).')
+@click.option('-r', '--refiner', type=REFINER, multiple=True, help='Refiner to use (can be used multiple times).')
+@click.option('-a', '--age', type=AGE, help='Filter videos newer than AGE, e.g. 12h, 1w2d.')
+@click.option('-d', '--directory', type=click.STRING, metavar='DIR', help='Directory where to save subtitles, '
+              'default is next to the video file.')
+@click.option('-e', '--encoding', type=click.STRING, metavar='ENC', help='Subtitle file encoding, default is to '
+              'preserve original encoding.')
+@click.option('-s', '--single', is_flag=True, default=False, help='Save subtitle without language code in the file '
+              'name, i.e. use .srt extension. Do not use this unless your media player requires it.')
+@click.option('-f', '--force', is_flag=True, default=False, help='Force download even if a subtitle already exist.')
+@click.option('-hi', '--hearing-impaired', is_flag=True, default=False, help='Prefer hearing impaired subtitles.')
+@click.option('-m', '--min-score', type=click.IntRange(0, 100), default=0, help='Minimum score for a subtitle '
+              'to be downloaded (0 to 100).')
+@click.option('-w', '--max-workers', type=click.IntRange(1, 50), default=None, help='Maximum number of threads to use.')
+@click.option('-z/-Z', '--archives/--no-archives', default=True, show_default=True, help='Scan archives for videos '
+              '(supported extensions: %s).' % ', '.join(ARCHIVE_EXTENSIONS))
+@click.option('-v', '--verbose', count=True, help='Increase verbosity.')
+@click.argument('path', type=click.Path(), required=True, nargs=-1)
+@click.pass_obj
+def download(obj, provider, refiner, language, age, directory, encoding, single, force, hearing_impaired, min_score,
+             max_workers, archives, verbose, path):
+    """Download best subtitles.
+
+    PATH can be an directory containing videos, a video file path or a video file name. It can be used multiple times.
+
+    If an existing subtitle is detected (external or embedded) in the correct language, the download is skipped for
+    the associated video.
+
+    """
+    # process parameters
+    language = set(language)
+
+    # scan videos
+    videos = []
+    ignored_videos = []
+    errored_paths = []
+    with click.progressbar(path, label='Collecting videos', item_show_func=lambda p: p or '') as bar:
+        for p in bar:
+            logger.debug('Collecting path %s', p)
+
+            # non-existing
+            if not os.path.exists(p):
+                try:
+                    video = Video.fromname(p)
+                except:
+                    logger.exception('Unexpected error while collecting non-existing path %s', p)
+                    errored_paths.append(p)
+                    continue
+                if not force:
+                    video.subtitle_languages |= set(search_external_subtitles(video.name, directory=directory).values())
+                refine(video, episode_refiners=refiner, movie_refiners=refiner, embedded_subtitles=not force)
+                videos.append(video)
+                continue
+
+            # directories
+            if os.path.isdir(p):
+                try:
+                    scanned_videos = scan_videos(p, age=age, archives=archives)
+                except:
+                    logger.exception('Unexpected error while collecting directory path %s', p)
+                    errored_paths.append(p)
+                    continue
+                for video in scanned_videos:
+                    if check_video(video, languages=language, age=age, undefined=single):
+                        if not force:
+                            video.subtitle_languages |= set(search_external_subtitles(video.name,
+                                                                                      directory=directory).values())
+                        refine(video, episode_refiners=refiner, movie_refiners=refiner, embedded_subtitles=not force)
+                        videos.append(video)
+                    else:
+                        ignored_videos.append(video)
+                continue
+
+            # other inputs
+            try:
+                video = scan_video(p)
+            except:
+                logger.exception('Unexpected error while collecting path %s', p)
+                errored_paths.append(p)
+                continue
+            if check_video(video, languages=language, age=age, undefined=single):
+                if not force:
+                    video.subtitle_languages |= set(search_external_subtitles(video.name, directory=directory).values())
+                refine(video, episode_refiners=refiner, movie_refiners=refiner, embedded_subtitles=not force)
+                videos.append(video)
+            else:
+                ignored_videos.append(video)
+
+    # output errored paths
+    if verbose > 0:
+        for p in errored_paths:
+            click.secho('%s errored' % p, fg='red')
+
+    # output ignored videos
+    if verbose > 1:
+        for video in ignored_videos:
+            click.secho('%s ignored - subtitles: %s / age: %d day%s' % (
+                os.path.split(video.name)[1],
+                ', '.join(str(s) for s in video.subtitle_languages) or 'none',
+                video.age.days,
+                's' if video.age.days > 1 else ''
+            ), fg='yellow')
+
+    # report collected videos
+    click.echo('%s video%s collected / %s video%s ignored / %s error%s' % (
+        click.style(str(len(videos)), bold=True, fg='green' if videos else None),
+        's' if len(videos) > 1 else '',
+        click.style(str(len(ignored_videos)), bold=True, fg='yellow' if ignored_videos else None),
+        's' if len(ignored_videos) > 1 else '',
+        click.style(str(len(errored_paths)), bold=True, fg='red' if errored_paths else None),
+        's' if len(errored_paths) > 1 else '',
+    ))
+
+    # exit if no video collected
+    if not videos:
+        return
+
+    # download best subtitles
+    downloaded_subtitles = defaultdict(list)
+    with AsyncProviderPool(max_workers=max_workers, providers=provider, provider_configs=obj['provider_configs']) as p:
+        with click.progressbar(videos, label='Downloading subtitles',
+                               item_show_func=lambda v: os.path.split(v.name)[1] if v is not None else '') as bar:
+            for v in bar:
+                scores = get_scores(v)
+                subtitles = p.download_best_subtitles(p.list_subtitles(v, language - v.subtitle_languages),
+                                                      v, language, min_score=scores['hash'] * min_score / 100,
+                                                      hearing_impaired=hearing_impaired, only_one=single)
+                downloaded_subtitles[v] = subtitles
+
+        if p.discarded_providers:
+            click.secho('Some providers have been discarded due to unexpected errors: %s' %
+                        ', '.join(p.discarded_providers), fg='yellow')
+
+    # save subtitles
+    total_subtitles = 0
+    for v, subtitles in downloaded_subtitles.items():
+        saved_subtitles = save_subtitles(v, subtitles, single=single, directory=directory, encoding=encoding)
+        total_subtitles += len(saved_subtitles)
+
+        if verbose > 0:
+            click.echo('%s subtitle%s downloaded for %s' % (click.style(str(len(saved_subtitles)), bold=True),
+                                                            's' if len(saved_subtitles) > 1 else '',
+                                                            os.path.split(v.name)[1]))
+
+        if verbose > 1:
+            for s in saved_subtitles:
+                matches = s.get_matches(v)
+                score = compute_score(s, v)
+
+                # score color
+                score_color = None
+                scores = get_scores(v)
+                if isinstance(v, Movie):
+                    if score < scores['title']:
+                        score_color = 'red'
+                    elif score < scores['title'] + scores['year'] + scores['release_group']:
+                        score_color = 'yellow'
+                    else:
+                        score_color = 'green'
+                elif isinstance(v, Episode):
+                    if score < scores['series'] + scores['season'] + scores['episode']:
+                        score_color = 'red'
+                    elif score < scores['series'] + scores['season'] + scores['episode'] + scores['release_group']:
+                        score_color = 'yellow'
+                    else:
+                        score_color = 'green'
+
+                # scale score from 0 to 100 taking out preferences
+                scaled_score = score
+                if s.hearing_impaired == hearing_impaired:
+                    scaled_score -= scores['hearing_impaired']
+                scaled_score *= 100 / scores['hash']
+
+                # echo some nice colored output
+                click.echo('  - [{score}] {language} subtitle from {provider_name} (match on {matches})'.format(
+                    score=click.style('{:5.1f}'.format(scaled_score), fg=score_color, bold=score >= scores['hash']),
+                    language=s.language.name if s.language.country is None else '%s (%s)' % (s.language.name,
+                                                                                             s.language.country.name),
+                    provider_name=s.provider_name,
+                    matches=', '.join(sorted(matches, key=scores.get, reverse=True))
+                ))
+
+    if verbose == 0:
+        click.echo('Downloaded %s subtitle%s' % (click.style(str(total_subtitles), bold=True),
+                                                 's' if total_subtitles > 1 else ''))

subliminal/converters/addic7ed.py

@@ -0,0 +1,32 @@
+# -*- coding: utf-8 -*-
+from babelfish import LanguageReverseConverter, language_converters
+
+
+class Addic7edConverter(LanguageReverseConverter):
+    def __init__(self):
+        self.name_converter = language_converters['name']
+        self.from_addic7ed = {u'Català': ('cat',), 'Chinese (Simplified)': ('zho',), 'Chinese (Traditional)': ('zho',),
+                              'Euskera': ('eus',), 'Galego': ('glg',), 'Greek': ('ell',), 'Malay': ('msa',),
+                              'Portuguese (Brazilian)': ('por', 'BR'), 'Serbian (Cyrillic)': ('srp', None, 'Cyrl'),
+                              'Serbian (Latin)': ('srp',), 'Spanish (Latin America)': ('spa',),
+                              'Spanish (Spain)': ('spa',)}
+        self.to_addic7ed = {('cat',): 'Català', ('zho',): 'Chinese (Simplified)', ('eus',): 'Euskera',
+                            ('glg',): 'Galego', ('ell',): 'Greek', ('msa',): 'Malay',
+                            ('por', 'BR'): 'Portuguese (Brazilian)', ('srp', None, 'Cyrl'): 'Serbian (Cyrillic)'}
+        self.codes = self.name_converter.codes | set(self.from_addic7ed.keys())
+
+    def convert(self, alpha3, country=None, script=None):
+        if (alpha3, country, script) in self.to_addic7ed:
+            return self.to_addic7ed[(alpha3, country, script)]
+        if (alpha3, country) in self.to_addic7ed:
+            return self.to_addic7ed[(alpha3, country)]
+        if (alpha3,) in self.to_addic7ed:
+            return self.to_addic7ed[(alpha3,)]
+
+        return self.name_converter.convert(alpha3, country, script)
+
+    def reverse(self, addic7ed):
+        if addic7ed in self.from_addic7ed:
+            return self.from_addic7ed[addic7ed]
+
+        return self.name_converter.reverse(addic7ed)

subliminal/converters/legendastv.py

@@ -0,0 +1,27 @@
+# -*- coding: utf-8 -*-
+from babelfish import LanguageReverseConverter
+
+from ..exceptions import ConfigurationError
+
+
+class LegendasTVConverter(LanguageReverseConverter):
+    def __init__(self):
+        self.from_legendastv = {1: ('por', 'BR'), 2: ('eng',), 3: ('spa',), 4: ('fra',), 5: ('deu',), 6: ('jpn',),
+                                7: ('dan',), 8: ('nor',), 9: ('swe',), 10: ('por',), 11: ('ara',), 12: ('ces',),
+                                13: ('zho',), 14: ('kor',), 15: ('bul',), 16: ('ita',), 17: ('pol',)}
+        self.to_legendastv = {v: k for k, v in self.from_legendastv.items()}
+        self.codes = set(self.from_legendastv.keys())
+
+    def convert(self, alpha3, country=None, script=None):
+        if (alpha3, country) in self.to_legendastv:
+            return self.to_legendastv[(alpha3, country)]
+        if (alpha3,) in self.to_legendastv:
+            return self.to_legendastv[(alpha3,)]
+
+        raise ConfigurationError('Unsupported language code for legendastv: %s, %s, %s' % (alpha3, country, script))
+
+    def reverse(self, legendastv):
+        if legendastv in self.from_legendastv:
+            return self.from_legendastv[legendastv]
+
+        raise ConfigurationError('Unsupported language number for legendastv: %s' % legendastv)

subliminal/converters/shooter.py

@@ -0,0 +1,23 @@
+# -*- coding: utf-8 -*-
+from babelfish import LanguageReverseConverter
+
+from ..exceptions import ConfigurationError
+
+
+class ShooterConverter(LanguageReverseConverter):
+    def __init__(self):
+        self.from_shooter = {'chn': ('zho',), 'eng': ('eng',)}
+        self.to_shooter = {v: k for k, v in self.from_shooter.items()}
+        self.codes = set(self.from_shooter.keys())
+
+    def convert(self, alpha3, country=None, script=None):
+        if (alpha3,) in self.to_shooter:
+            return self.to_shooter[(alpha3,)]
+
+        raise ConfigurationError('Unsupported language for shooter: %s, %s, %s' % (alpha3, country, script))
+
+    def reverse(self, shooter):
+        if shooter in self.from_shooter:
+            return self.from_shooter[shooter]
+
+        raise ConfigurationError('Unsupported language code for shooter: %s' % shooter)

subliminal/converters/thesubdb.py

@@ -0,0 +1,26 @@
+# -*- coding: utf-8 -*-
+from babelfish import LanguageReverseConverter
+
+from ..exceptions import ConfigurationError
+
+
+class TheSubDBConverter(LanguageReverseConverter):
+    def __init__(self):
+        self.from_thesubdb = {'en': ('eng',), 'es': ('spa',), 'fr': ('fra',), 'it': ('ita',), 'nl': ('nld',),
+                              'pl': ('pol',), 'pt': ('por', 'BR'), 'ro': ('ron',), 'sv': ('swe',), 'tr': ('tur',)}
+        self.to_thesubdb = {v: k for k, v in self.from_thesubdb.items()}
+        self.codes = set(self.from_thesubdb.keys())
+
+    def convert(self, alpha3, country=None, script=None):
+        if (alpha3, country) in self.to_thesubdb:
+            return self.to_thesubdb[(alpha3, country)]
+        if (alpha3,) in self.to_thesubdb:
+            return self.to_thesubdb[(alpha3,)]
+
+        raise ConfigurationError('Unsupported language for thesubdb: %s, %s, %s' % (alpha3, country, script))
+
+    def reverse(self, thesubdb):
+        if thesubdb in self.from_thesubdb:
+            return self.from_thesubdb[thesubdb]
+
+        raise ConfigurationError('Unsupported language code for thesubdb: %s' % thesubdb)

subliminal/converters/tvsubtitles.py

@@ -0,0 +1,25 @@
+# -*- coding: utf-8 -*-
+from babelfish import LanguageReverseConverter, language_converters
+
+
+class TVsubtitlesConverter(LanguageReverseConverter):
+    def __init__(self):
+        self.alpha2_converter = language_converters['alpha2']
+        self.from_tvsubtitles = {'br': ('por', 'BR'), 'ua': ('ukr',), 'gr': ('ell',), 'cn': ('zho',), 'jp': ('jpn',),
+                                 'cz': ('ces',)}
+        self.to_tvsubtitles = {v: k for k, v in self.from_tvsubtitles.items()}
+        self.codes = self.alpha2_converter.codes | set(self.from_tvsubtitles.keys())
+
+    def convert(self, alpha3, country=None, script=None):
+        if (alpha3, country) in self.to_tvsubtitles:
+            return self.to_tvsubtitles[(alpha3, country)]
+        if (alpha3,) in self.to_tvsubtitles:
+            return self.to_tvsubtitles[(alpha3,)]
+
+        return self.alpha2_converter.convert(alpha3, country, script)
+
+    def reverse(self, tvsubtitles):
+        if tvsubtitles in self.from_tvsubtitles:
+            return self.from_tvsubtitles[tvsubtitles]
+
+        return self.alpha2_converter.reverse(tvsubtitles)

subliminal/core.py

@@ -1,275 +1,705 @@
 # -*- coding: utf-8 -*-
-# Copyright 2011-2012 Antoine Bertin <diaoulael@gmail.com>
-#
-# This file is part of subliminal.
-#
-# subliminal is free software; you can redistribute it and/or modify it under
-# the terms of the GNU Lesser General Public License as published by
-# the Free Software Foundation; either version 3 of the License, or
-# (at your option) any later version.
-#
-# subliminal is distributed in the hope that it will be useful,
-# but WITHOUT ANY WARRANTY; without even the implied warranty of
-# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
-# GNU Lesser General Public License for more details.
-#
-# You should have received a copy of the GNU Lesser General Public License
-# along with subliminal.  If not, see <http://www.gnu.org/licenses/>.
-from .exceptions import DownloadFailedError
-from .services import ServiceConfig
-from .tasks import DownloadTask, ListTask
-from .utils import get_keywords
-from .videos import Episode, Movie, scan
-from .language import Language
 from collections import defaultdict
-from itertools import groupby
-import bs4
-import guessit
+from concurrent.futures import ThreadPoolExecutor
+from datetime import datetime
+import io
+import itertools
 import logging
+import operator
+import os.path
+import socket
 
+from babelfish import Language, LanguageReverseError
+from guessit import guessit
+from rarfile import NotRarFile, RarCannotExec, RarFile
+import requests
+
+from .extensions import provider_manager, refiner_manager
+from .score import compute_score as default_compute_score
+from .subtitle import SUBTITLE_EXTENSIONS, get_subtitle_path
+from .utils import hash_napiprojekt, hash_opensubtitles, hash_shooter, hash_thesubdb
+from .video import VIDEO_EXTENSIONS, Episode, Movie, Video
+
+#: Supported archive extensions
+ARCHIVE_EXTENSIONS = ('.rar',)
 
-__all__ = ['SERVICES', 'LANGUAGE_INDEX', 'SERVICE_INDEX', 'SERVICE_CONFIDENCE', 'MATCHING_CONFIDENCE',
-           'create_list_tasks', 'create_download_tasks', 'consume_task', 'matching_confidence',
-           'key_subtitles', 'group_by_video']
 logger = logging.getLogger(__name__)
-SERVICES = ['opensubtitles', 'bierdopje', 'subswiki', 'subtitulos', 'thesubdb', 'addic7ed', 'tvsubtitles']
-LANGUAGE_INDEX, SERVICE_INDEX, SERVICE_CONFIDENCE, MATCHING_CONFIDENCE = range(4)
 
 
-def create_list_tasks(paths, languages, services, force, multi, cache_dir, max_depth, scan_filter):
-    """Create a list of :class:`~subliminal.tasks.ListTask` from one or more paths using the given criteria
+class ProviderPool(object):
+    """A pool of providers with the same API as a single :class:`~subliminal.providers.Provider`.
 
-    :param paths: path(s) to video file or folder
-    :type paths: string or list
-    :param set languages: languages to search for
-    :param list services: services to use for the search
-    :param bool force: force searching for subtitles even if some are detected
-    :param bool multi: search multiple languages for the same video
-    :param string cache_dir: path to the cache directory to use
-    :param int max_depth: maximum depth for scanning entries
-    :param function scan_filter: filter function that takes a path as argument and returns a boolean indicating whether it has to be filtered out (``True``) or not (``False``)
-    :return: the created tasks
-    :rtype: list of :class:`~subliminal.tasks.ListTask`
+    It has a few extra features:
+
+        * Lazy loads providers when needed and supports the `with` statement to :meth:`terminate`
+          the providers on exit.
+        * Automatically discard providers on failure.
+
+    :param list providers: name of providers to use, if not all.
+    :param dict provider_configs: provider configuration as keyword arguments per provider name to pass when
+        instanciating the :class:`~subliminal.providers.Provider`.
 
     """
-    scan_result = []
-    for p in paths:
-        scan_result.extend(scan(p, max_depth, scan_filter))
-    logger.debug(u'Found %d videos in %r with maximum depth %d' % (len(scan_result), paths, max_depth))
-    tasks = []
-    config = ServiceConfig(multi, cache_dir)
-    services = filter_services(services)
-    for video, detected_subtitles in scan_result:
-        detected_languages = set(s.language for s in detected_subtitles)
-        wanted_languages = languages.copy()
-        if not force and multi:
-            wanted_languages -= detected_languages
-            if not wanted_languages:
-                logger.debug(u'No need to list multi subtitles %r for %r because %r detected' % (languages, video, detected_languages))
+    def __init__(self, providers=None, provider_configs=None):
+        #: Name of providers to use
+        self.providers = providers or provider_manager.names()
+
+        #: Provider configuration
+        self.provider_configs = provider_configs or {}
+
+        #: Initialized providers
+        self.initialized_providers = {}
+
+        #: Discarded providers
+        self.discarded_providers = set()
+
+    def __enter__(self):
+        return self
+
+    def __exit__(self, exc_type, exc_value, traceback):
+        self.terminate()
+
+    def __getitem__(self, name):
+        if name not in self.providers:
+            raise KeyError
+        if name not in self.initialized_providers:
+            logger.info('Initializing provider %s', name)
+            provider = provider_manager[name].plugin(**self.provider_configs.get(name, {}))
+            provider.initialize()
+            self.initialized_providers[name] = provider
+
+        return self.initialized_providers[name]
+
+    def __delitem__(self, name):
+        if name not in self.initialized_providers:
+            raise KeyError(name)
+
+        try:
+            logger.info('Terminating provider %s', name)
+            self.initialized_providers[name].terminate()
+        except (requests.Timeout, socket.timeout):
+            logger.error('Provider %r timed out, improperly terminated', name)
+        except:
+            logger.exception('Provider %r terminated unexpectedly', name)
+
+        del self.initialized_providers[name]
+
+    def __iter__(self):
+        return iter(self.initialized_providers)
+
+    def list_subtitles_provider(self, provider, video, languages):
+        """List subtitles with a single provider.
+
+        The video and languages are checked against the provider.
+
+        :param str provider: name of the provider.
+        :param video: video to list subtitles for.
+        :type video: :class:`~subliminal.video.Video`
+        :param languages: languages to search for.
+        :type languages: set of :class:`~babelfish.language.Language`
+        :return: found subtitles.
+        :rtype: list of :class:`~subliminal.subtitle.Subtitle` or None
+
+        """
+        # check video validity
+        if not provider_manager[provider].plugin.check(video):
+            logger.info('Skipping provider %r: not a valid video', provider)
+            return []
+
+        # check supported languages
+        provider_languages = provider_manager[provider].plugin.languages & languages
+        if not provider_languages:
+            logger.info('Skipping provider %r: no language to search for', provider)
+            return []
+
+        # list subtitles
+        logger.info('Listing subtitles with provider %r and languages %r', provider, provider_languages)
+        try:
+            return self[provider].list_subtitles(video, provider_languages)
+        except (requests.Timeout, socket.timeout):
+            logger.error('Provider %r timed out', provider)
+        except:
+            logger.exception('Unexpected error in provider %r', provider)
+
+    def list_subtitles(self, video, languages):
+        """List subtitles.
+
+        :param video: video to list subtitles for.
+        :type video: :class:`~subliminal.video.Video`
+        :param languages: languages to search for.
+        :type languages: set of :class:`~babelfish.language.Language`
+        :return: found subtitles.
+        :rtype: list of :class:`~subliminal.subtitle.Subtitle`
+
+        """
+        subtitles = []
+
+        for name in self.providers:
+            # check discarded providers
+            if name in self.discarded_providers:
+                logger.debug('Skipping discarded provider %r', name)
                 continue
-        if not force and not multi and Language('Undetermined') in detected_languages:
-            logger.debug(u'No need to list single subtitles %r for %r because one detected' % (languages, video))
-            continue
-        logger.debug(u'Listing subtitles %r for %r with services %r' % (wanted_languages, video, services))
-        for service_name in services:
-            mod = __import__('services.' + service_name, globals=globals(), locals=locals(), fromlist=['Service'], level=-1)
-            service = mod.Service
-            if not service.check_validity(video, wanted_languages):
+
+            # list subtitles
+            provider_subtitles = self.list_subtitles_provider(name, video, languages)
+            if provider_subtitles is None:
+                logger.info('Discarding provider %s', name)
+                self.discarded_providers.add(name)
                 continue
-            task = ListTask(video, wanted_languages & service.languages, service_name, config)
-            logger.debug(u'Created task %r' % task)
-            tasks.append(task)
-    return tasks
 
+            # add the subtitles
+            subtitles.extend(provider_subtitles)
 
-def create_download_tasks(subtitles_by_video, languages, multi):
-    """Create a list of :class:`~subliminal.tasks.DownloadTask` from a list results grouped by video
+        return subtitles
 
-    :param subtitles_by_video: :class:`~subliminal.tasks.ListTask` results with ordered subtitles
-    :type subtitles_by_video: dict of :class:`~subliminal.videos.Video` => [:class:`~subliminal.subtitles.Subtitle`]
-    :param languages: languages in preferred order
-    :type languages: :class:`~subliminal.language.language_list`
-    :param bool multi: download multiple languages for the same video
-    :return: the created tasks
-    :rtype: list of :class:`~subliminal.tasks.DownloadTask`
+    def download_subtitle(self, subtitle):
+        """Download `subtitle`'s :attr:`~subliminal.subtitle.Subtitle.content`.
 
-    """
-    tasks = []
-    for video, subtitles in subtitles_by_video.iteritems():
-        if not subtitles:
-            continue
-        if not multi:
-            task = DownloadTask(video, list(subtitles))
-            logger.debug(u'Created task %r' % task)
-            tasks.append(task)
-            continue
-        for _, by_language in groupby(subtitles, lambda s: languages.index(s.language)):
-            task = DownloadTask(video, list(by_language))
-            logger.debug(u'Created task %r' % task)
-            tasks.append(task)
-    return tasks
+        :param subtitle: subtitle to download.
+        :type subtitle: :class:`~subliminal.subtitle.Subtitle`
+        :return: `True` if the subtitle has been successfully downloaded, `False` otherwise.
+        :rtype: bool
 
+        """
+        # check discarded providers
+        if subtitle.provider_name in self.discarded_providers:
+            logger.warning('Provider %r is discarded', subtitle.provider_name)
+            return False
 
-def consume_task(task, services=None):
-    """Consume a task. If the ``services`` parameter is given, the function will attempt
-    to get the service from it. In case the service is not in ``services``, it will be initialized
-    and put in ``services``
+        logger.info('Downloading subtitle %r', subtitle)
+        try:
+            self[subtitle.provider_name].download_subtitle(subtitle)
+        except (requests.Timeout, socket.timeout):
+            logger.error('Provider %r timed out, discarding it', subtitle.provider_name)
+            self.discarded_providers.add(subtitle.provider_name)
+            return False
+        except:
+            logger.exception('Unexpected error in provider %r, discarding it', subtitle.provider_name)
+            self.discarded_providers.add(subtitle.provider_name)
+            return False
 
-    :param task: task to consume
-    :type task: :class:`~subliminal.tasks.ListTask` or :class:`~subliminal.tasks.DownloadTask`
-    :param dict services: mapping between the service name and an instance of this service
-    :return: the result of the task
-    :rtype: list of :class:`~subliminal.subtitles.ResultSubtitle`
+        # check subtitle validity
+        if not subtitle.is_valid():
+            logger.error('Invalid subtitle')
+            return False
 
-    """
-    if services is None:
-        services = {}
-    logger.info(u'Consuming %r' % task)
-    result = None
-    if isinstance(task, ListTask):
-        service = get_service(services, task.service, config=task.config)
-        result = service.list(task.video, task.languages)
-    elif isinstance(task, DownloadTask):
-        for subtitle in task.subtitles:
-            service = get_service(services, subtitle.service)
-            try:
-                service.download(subtitle)
-                result = [subtitle]
+        return True
+
+    def download_best_subtitles(self, subtitles, video, languages, min_score=0, hearing_impaired=False, only_one=False,
+                                compute_score=None):
+        """Download the best matching subtitles.
+
+        :param subtitles: the subtitles to use.
+        :type subtitles: list of :class:`~subliminal.subtitle.Subtitle`
+        :param video: video to download subtitles for.
+        :type video: :class:`~subliminal.video.Video`
+        :param languages: languages to download.
+        :type languages: set of :class:`~babelfish.language.Language`
+        :param int min_score: minimum score for a subtitle to be downloaded.
+        :param bool hearing_impaired: hearing impaired preference.
+        :param bool only_one: download only one subtitle, not one per language.
+        :param compute_score: function that takes `subtitle` and `video` as positional arguments,
+            `hearing_impaired` as keyword argument and returns the score.
+        :return: downloaded subtitles.
+        :rtype: list of :class:`~subliminal.subtitle.Subtitle`
+
+        """
+        compute_score = compute_score or default_compute_score
+
+        # sort subtitles by score
+        scored_subtitles = sorted([(s, compute_score(s, video, hearing_impaired=hearing_impaired))
+                                  for s in subtitles], key=operator.itemgetter(1), reverse=True)
+
+        # download best subtitles, falling back on the next on error
+        downloaded_subtitles = []
+        for subtitle, score in scored_subtitles:
+            # check score
+            if score < min_score:
+                logger.info('Score %d is below min_score (%d)', score, min_score)
                 break
-            except DownloadFailedError:
-                logger.warning(u'Could not download subtitle %r, trying next' % subtitle)
+
+            # check downloaded languages
+            if subtitle.language in set(s.language for s in downloaded_subtitles):
+                logger.debug('Skipping subtitle: %r already downloaded', subtitle.language)
                 continue
-        if result is None:
-            logger.error(u'No subtitles could be downloaded for video %r' % task.video)
-    return result
+
+            # download
+            if self.download_subtitle(subtitle):
+                downloaded_subtitles.append(subtitle)
+
+            # stop when all languages are downloaded
+            if set(s.language for s in downloaded_subtitles) == languages:
+                logger.debug('All languages downloaded')
+                break
+
+            # stop if only one subtitle is requested
+            if only_one:
+                logger.debug('Only one subtitle downloaded')
+                break
+
+        return downloaded_subtitles
+
+    def terminate(self):
+        """Terminate all the :attr:`initialized_providers`."""
+        logger.debug('Terminating initialized providers')
+        for name in list(self.initialized_providers):
+            del self[name]
 
 
-def matching_confidence(video, subtitle):
-    """Compute the probability (confidence) that the subtitle matches the video
+class AsyncProviderPool(ProviderPool):
+    """Subclass of :class:`ProviderPool` with asynchronous support for :meth:`~ProviderPool.list_subtitles`.
 
-    :param video: video to match
-    :type video: :class:`~subliminal.videos.Video`
-    :param subtitle: subtitle to match
-    :type subtitle: :class:`~subliminal.subtitles.Subtitle`
-    :return: the matching probability
-    :rtype: float
+    :param int max_workers: maximum number of threads to use. If `None`, :attr:`max_workers` will be set
+        to the number of :attr:`~ProviderPool.providers`.
 
     """
-    guess = guessit.guess_file_info(subtitle.release, 'autodetect')
-    video_keywords = get_keywords(video.guess)
-    subtitle_keywords = get_keywords(guess) | subtitle.keywords
-    logger.debug(u'Video keywords %r - Subtitle keywords %r' % (video_keywords, subtitle_keywords))
-    replacement = {'keywords': len(video_keywords & subtitle_keywords)}
-    if isinstance(video, Episode):
-        replacement.update({'series': 0, 'season': 0, 'episode': 0})
-        matching_format = '{series:b}{season:b}{episode:b}{keywords:03b}'
-        best = matching_format.format(series=1, season=1, episode=1, keywords=len(video_keywords))
-        if guess['type'] in ['episode', 'episodesubtitle']:
-            if 'series' in guess and guess['series'].lower() == video.series.lower():
-                replacement['series'] = 1
-            if 'season' in guess and guess['season'] == video.season:
-                replacement['season'] = 1
-            if 'episodeNumber' in guess and guess['episodeNumber'] == video.episode:
-                replacement['episode'] = 1
-    elif isinstance(video, Movie):
-        replacement.update({'title': 0, 'year': 0})
-        matching_format = '{title:b}{year:b}{keywords:03b}'
-        best = matching_format.format(title=1, year=1, keywords=len(video_keywords))
-        if guess['type'] in ['movie', 'moviesubtitle']:
-            if 'title' in guess and guess['title'].lower() == video.title.lower():
-                replacement['title'] = 1
-            if 'year' in guess and guess['year'] == video.year:
-                replacement['year'] = 1
+    def __init__(self, max_workers=None, *args, **kwargs):
+        super(AsyncProviderPool, self).__init__(*args, **kwargs)
+
+        #: Maximum number of threads to use
+        self.max_workers = max_workers or len(self.providers)
+
+    def list_subtitles_provider(self, provider, video, languages):
+        return provider, super(AsyncProviderPool, self).list_subtitles_provider(provider, video, languages)
+
+    def list_subtitles(self, video, languages):
+        subtitles = []
+
+        with ThreadPoolExecutor(self.max_workers) as executor:
+            for provider, provider_subtitles in executor.map(self.list_subtitles_provider, self.providers,
+                                                             itertools.repeat(video, len(self.providers)),
+                                                             itertools.repeat(languages, len(self.providers))):
+                # discard provider that failed
+                if provider_subtitles is None:
+                    logger.info('Discarding provider %s', provider)
+                    self.discarded_providers.add(provider)
+                    continue
+
+                # add subtitles
+                subtitles.extend(provider_subtitles)
+
+        return subtitles
+
+
+def check_video(video, languages=None, age=None, undefined=False):
+    """Perform some checks on the `video`.
+
+    All the checks are optional. Return `False` if any of this check fails:
+
+        * `languages` already exist in `video`'s :attr:`~subliminal.video.Video.subtitle_languages`.
+        * `video` is older than `age`.
+        * `video` has an `undefined` language in :attr:`~subliminal.video.Video.subtitle_languages`.
+
+    :param video: video to check.
+    :type video: :class:`~subliminal.video.Video`
+    :param languages: desired languages.
+    :type languages: set of :class:`~babelfish.language.Language`
+    :param datetime.timedelta age: maximum age of the video.
+    :param bool undefined: fail on existing undefined language.
+    :return: `True` if the video passes the checks, `False` otherwise.
+    :rtype: bool
+
+    """
+    # language test
+    if languages and not (languages - video.subtitle_languages):
+        logger.debug('All languages %r exist', languages)
+        return False
+
+    # age test
+    if age and video.age > age:
+        logger.debug('Video is older than %r', age)
+        return False
+
+    # undefined test
+    if undefined and Language('und') in video.subtitle_languages:
+        logger.debug('Undefined language found')
+        return False
+
+    return True
+
+
+def search_external_subtitles(path, directory=None):
+    """Search for external subtitles from a video `path` and their associated language.
+
+    Unless `directory` is provided, search will be made in the same directory as the video file.
+
+    :param str path: path to the video.
+    :param str directory: directory to search for subtitles.
+    :return: found subtitles with their languages.
+    :rtype: dict
+
+    """
+    # split path
+    dirpath, filename = os.path.split(path)
+    dirpath = dirpath or '.'
+    fileroot, fileext = os.path.splitext(filename)
+
+    # search for subtitles
+    subtitles = {}
+    for p in os.listdir(directory or dirpath):
+        # keep only valid subtitle filenames
+        if not p.startswith(fileroot) or not p.endswith(SUBTITLE_EXTENSIONS):
+            continue
+
+        # extract the potential language code
+        language = Language('und')
+        language_code = p[len(fileroot):-len(os.path.splitext(p)[1])].replace(fileext, '').replace('_', '-')[1:]
+        if language_code:
+            try:
+                language = Language.fromietf(language_code)
+            except (ValueError, LanguageReverseError):
+                logger.error('Cannot parse language code %r', language_code)
+
+        subtitles[p] = language
+
+    logger.debug('Found subtitles %r', subtitles)
+
+    return subtitles
+
+
+def scan_video(path):
+    """Scan a video from a `path`.
+
+    :param str path: existing path to the video.
+    :return: the scanned video.
+    :rtype: :class:`~subliminal.video.Video`
+
+    """
+    # check for non-existing path
+    if not os.path.exists(path):
+        raise ValueError('Path does not exist')
+
+    # check video extension
+    if not path.endswith(VIDEO_EXTENSIONS):
+        raise ValueError('%r is not a valid video extension' % os.path.splitext(path)[1])
+
+    dirpath, filename = os.path.split(path)
+    logger.info('Scanning video %r in %r', filename, dirpath)
+
+    # guess
+    video = Video.fromguess(path, guessit(path))
+
+    # size and hashes
+    video.size = os.path.getsize(path)
+    if video.size > 10485760:
+        logger.debug('Size is %d', video.size)
+        video.hashes['opensubtitles'] = hash_opensubtitles(path)
+        video.hashes['shooter'] = hash_shooter(path)
+        video.hashes['thesubdb'] = hash_thesubdb(path)
+        video.hashes['napiprojekt'] = hash_napiprojekt(path)
+        logger.debug('Computed hashes %r', video.hashes)
     else:
-        logger.debug(u'Not able to compute confidence for %r' % video)
-        return 0.0
-    logger.debug(u'Found %r' % replacement)
-    confidence = float(int(matching_format.format(**replacement), 2)) / float(int(best, 2))
-    logger.info(u'Computed confidence %.4f for %r and %r' % (confidence, video, subtitle))
-    return confidence
+        logger.warning('Size is lower than 10MB: hashes not computed')
+
+    return video
 
 
-def get_service(services, service_name, config=None):
-    """Get a service from its name in the service dict with the specified config.
-    If the service does not exist in the service dict, it is created and added to the dict.
+def scan_archive(path):
+    """Scan an archive from a `path`.
 
-    :param dict services: dict where to get existing services or put created ones
-    :param string service_name: name of the service to get
-    :param config: config to use for the service
-    :type config: :class:`~subliminal.services.ServiceConfig` or None
-    :return: the corresponding service
-    :rtype: :class:`~subliminal.services.ServiceBase`
+    :param str path: existing path to the archive.
+    :return: the scanned video.
+    :rtype: :class:`~subliminal.video.Video`
 
     """
-    if service_name not in services:
-        mod = __import__('services.' + service_name, globals=globals(), locals=locals(), fromlist=['Service'], level=-1)
-        services[service_name] = mod.Service()
-        services[service_name].init()
-    services[service_name].config = config
-    return services[service_name]
+    # check for non-existing path
+    if not os.path.exists(path):
+        raise ValueError('Path does not exist')
+
+    # check video extension
+    if not path.endswith(ARCHIVE_EXTENSIONS):
+        raise ValueError('%r is not a valid archive extension' % os.path.splitext(path)[1])
+
+    dirpath, filename = os.path.split(path)
+    logger.info('Scanning archive %r in %r', filename, dirpath)
+
+    # rar extension
+    if filename.endswith('.rar'):
+        rar = RarFile(path)
+
+        # filter on video extensions
+        rar_filenames = [f for f in rar.namelist() if f.endswith(VIDEO_EXTENSIONS)]
+
+        # no video found
+        if not rar_filenames:
+            raise ValueError('No video in archive')
+
+        # more than one video found
+        if len(rar_filenames) > 1:
+            raise ValueError('More than one video in archive')
+
+        # guess
+        rar_filename = rar_filenames[0]
+        rar_filepath = os.path.join(dirpath, rar_filename)
+        video = Video.fromguess(rar_filepath, guessit(rar_filepath))
+
+        # size
+        video.size = rar.getinfo(rar_filename).file_size
+    else:
+        raise ValueError('Unsupported extension %r' % os.path.splitext(path)[1])
+
+    return video
 
 
-def key_subtitles(subtitle, video, languages, services, order):
-    """Create a key to sort subtitle using the given order
+def scan_videos(path, age=None, archives=True):
+    """Scan `path` for videos and their subtitles.
 
-    :param subtitle: subtitle to sort
-    :type subtitle: :class:`~subliminal.subtitles.ResultSubtitle`
-    :param video: video to match
-    :type video: :class:`~subliminal.videos.Video`
-    :param list languages: languages in preferred order
-    :param list services: services in preferred order
-    :param order: preferred order for subtitles sorting
-    :type list: list of :data:`LANGUAGE_INDEX`, :data:`SERVICE_INDEX`, :data:`SERVICE_CONFIDENCE`, :data:`MATCHING_CONFIDENCE`
-    :return: a key ready to use for subtitles sorting
-    :rtype: int
+    See :func:`refine` to find additional information for the video.
+
+    :param str path: existing directory path to scan.
+    :param datetime.timedelta age: maximum age of the video or archive.
+    :param bool archives: scan videos in archives.
+    :return: the scanned videos.
+    :rtype: list of :class:`~subliminal.video.Video`
 
     """
-    key = ''
-    for sort_item in order:
-        if sort_item == LANGUAGE_INDEX:
-            key += '{0:03d}'.format(len(languages) - languages.index(subtitle.language) - 1)
-            key += '{0:01d}'.format(subtitle.language == languages[languages.index(subtitle.language)])
-        elif sort_item == SERVICE_INDEX:
-            key += '{0:02d}'.format(len(services) - services.index(subtitle.service) - 1)
-        elif sort_item == SERVICE_CONFIDENCE:
-            key += '{0:04d}'.format(int(subtitle.confidence * 1000))
-        elif sort_item == MATCHING_CONFIDENCE:
-            confidence = 0
-            if subtitle.release:
-                confidence = matching_confidence(video, subtitle)
-            key += '{0:04d}'.format(int(confidence * 1000))
-    return int(key)
+    # check for non-existing path
+    if not os.path.exists(path):
+        raise ValueError('Path does not exist')
+
+    # check for non-directory path
+    if not os.path.isdir(path):
+        raise ValueError('Path is not a directory')
+
+    # walk the path
+    videos = []
+    for dirpath, dirnames, filenames in os.walk(path):
+        logger.debug('Walking directory %r', dirpath)
+
+        # remove badly encoded and hidden dirnames
+        for dirname in list(dirnames):
+            if dirname.startswith('.'):
+                logger.debug('Skipping hidden dirname %r in %r', dirname, dirpath)
+                dirnames.remove(dirname)
+
+        # scan for videos
+        for filename in filenames:
+            # filter on videos and archives
+            if not (filename.endswith(VIDEO_EXTENSIONS) or archives and filename.endswith(ARCHIVE_EXTENSIONS)):
+                continue
+
+            # skip hidden files
+            if filename.startswith('.'):
+                logger.debug('Skipping hidden filename %r in %r', filename, dirpath)
+                continue
+
+            # reconstruct the file path
+            filepath = os.path.join(dirpath, filename)
+
+            # skip links
+            if os.path.islink(filepath):
+                logger.debug('Skipping link %r in %r', filename, dirpath)
+                continue
+
+            # skip old files
+            if age and datetime.utcnow() - datetime.utcfromtimestamp(os.path.getmtime(filepath)) > age:
+                logger.debug('Skipping old file %r in %r', filename, dirpath)
+                continue
+
+            # scan
+            if filename.endswith(VIDEO_EXTENSIONS):  # video
+                try:
+                    video = scan_video(filepath)
+                except ValueError:  # pragma: no cover
+                    logger.exception('Error scanning video')
+                    continue
+            elif archives and filename.endswith(ARCHIVE_EXTENSIONS):  # archive
+                try:
+                    video = scan_archive(filepath)
+                except (NotRarFile, RarCannotExec, ValueError):  # pragma: no cover
+                    logger.exception('Error scanning archive')
+                    continue
+            else:  # pragma: no cover
+                raise ValueError('Unsupported file %r' % filename)
+
+            videos.append(video)
+
+    return videos
 
 
-def group_by_video(list_results):
-    """Group the results of :class:`ListTasks <subliminal.tasks.ListTask>` into a
-    dictionary of :class:`~subliminal.videos.Video` => :class:`~subliminal.subtitles.Subtitle`
+def refine(video, episode_refiners=None, movie_refiners=None, **kwargs):
+    """Refine a video using :ref:`refiners`.
 
-    :param list_results:
-    :type list_results: list of result of :class:`~subliminal.tasks.ListTask`
-    :return: subtitles grouped by videos
-    :rtype: dict of :class:`~subliminal.videos.Video` => [:class:`~subliminal.subtitles.Subtitle`]
+    .. note::
+
+        Exceptions raised in refiners are silently passed and logged.
+
+    :param video: the video to refine.
+    :type video: :class:`~subliminal.video.Video`
+    :param tuple episode_refiners: refiners to use for episodes.
+    :param tuple movie_refiners: refiners to use for movies.
+    :param \*\*kwargs: additional parameters for the :func:`~subliminal.refiners.refine` functions.
 
     """
-    result = defaultdict(list)
-    for video, subtitles in list_results:
-        result[video] += subtitles or []
-    return result
+    refiners = ()
+    if isinstance(video, Episode):
+        refiners = episode_refiners or ('metadata', 'tvdb', 'omdb')
+    elif isinstance(video, Movie):
+        refiners = movie_refiners or ('metadata', 'omdb')
+    for refiner in refiners:
+        logger.info('Refining video with %s', refiner)
+        try:
+            refiner_manager[refiner].plugin(video, **kwargs)
+        except:
+            logger.exception('Failed to refine video')
 
 
-def filter_services(services):
-    """Filter out services that are not available because of a missing feature
+def list_subtitles(videos, languages, pool_class=ProviderPool, **kwargs):
+    """List subtitles.
 
-    :param list services: service names to filter
-    :return: a copy of the initial list of service names without unavailable ones
-    :rtype: list
+    The `videos` must pass the `languages` check of :func:`check_video`.
+
+    :param videos: videos to list subtitles for.
+    :type videos: set of :class:`~subliminal.video.Video`
+    :param languages: languages to search for.
+    :type languages: set of :class:`~babelfish.language.Language`
+    :param pool_class: class to use as provider pool.
+    :type pool_class: :class:`ProviderPool`, :class:`AsyncProviderPool` or similar
+    :param \*\*kwargs: additional parameters for the provided `pool_class` constructor.
+    :return: found subtitles per video.
+    :rtype: dict of :class:`~subliminal.video.Video` to list of :class:`~subliminal.subtitle.Subtitle`
 
     """
-    filtered_services = services[:]
-    for service_name in services:
-        mod = __import__('services.' + service_name, globals=globals(), locals=locals(), fromlist=['Service'], level=-1)
-        service = mod.Service
-        if service.required_features is not None and bs4.builder_registry.lookup(*service.required_features) is None:
-            logger.warning(u'Service %s not available: none of available features could be used. One of %r required' % (service_name, service.required_features))
-            filtered_services.remove(service_name)
-    return filtered_services
+    listed_subtitles = defaultdict(list)
+
+    # check videos
+    checked_videos = []
+    for video in videos:
+        if not check_video(video, languages=languages):
+            logger.info('Skipping video %r', video)
+            continue
+        checked_videos.append(video)
+
+    # return immediately if no video passed the checks
+    if not checked_videos:
+        return listed_subtitles
+
+    # list subtitles
+    with pool_class(**kwargs) as pool:
+        for video in checked_videos:
+            logger.info('Listing subtitles for %r', video)
+            subtitles = pool.list_subtitles(video, languages - video.subtitle_languages)
+            listed_subtitles[video].extend(subtitles)
+            logger.info('Found %d subtitle(s)', len(subtitles))
+
+    return listed_subtitles
+
+
+def download_subtitles(subtitles, pool_class=ProviderPool, **kwargs):
+    """Download :attr:`~subliminal.subtitle.Subtitle.content` of `subtitles`.
+
+    :param subtitles: subtitles to download.
+    :type subtitles: list of :class:`~subliminal.subtitle.Subtitle`
+    :param pool_class: class to use as provider pool.
+    :type pool_class: :class:`ProviderPool`, :class:`AsyncProviderPool` or similar
+    :param \*\*kwargs: additional parameters for the provided `pool_class` constructor.
+
+    """
+    with pool_class(**kwargs) as pool:
+        for subtitle in subtitles:
+            logger.info('Downloading subtitle %r', subtitle)
+            pool.download_subtitle(subtitle)
+
+
+def download_best_subtitles(videos, languages, min_score=0, hearing_impaired=False, only_one=False, compute_score=None,
+                            pool_class=ProviderPool, **kwargs):
+    """List and download the best matching subtitles.
+
+    The `videos` must pass the `languages` and `undefined` (`only_one`) checks of :func:`check_video`.
+
+    :param videos: videos to download subtitles for.
+    :type videos: set of :class:`~subliminal.video.Video`
+    :param languages: languages to download.
+    :type languages: set of :class:`~babelfish.language.Language`
+    :param int min_score: minimum score for a subtitle to be downloaded.
+    :param bool hearing_impaired: hearing impaired preference.
+    :param bool only_one: download only one subtitle, not one per language.
+    :param compute_score: function that takes `subtitle` and `video` as positional arguments,
+        `hearing_impaired` as keyword argument and returns the score.
+    :param pool_class: class to use as provider pool.
+    :type pool_class: :class:`ProviderPool`, :class:`AsyncProviderPool` or similar
+    :param \*\*kwargs: additional parameters for the provided `pool_class` constructor.
+    :return: downloaded subtitles per video.
+    :rtype: dict of :class:`~subliminal.video.Video` to list of :class:`~subliminal.subtitle.Subtitle`
+
+    """
+    downloaded_subtitles = defaultdict(list)
+
+    # check videos
+    checked_videos = []
+    for video in videos:
+        if not check_video(video, languages=languages, undefined=only_one):
+            logger.info('Skipping video %r', video)
+            continue
+        checked_videos.append(video)
+
+    # return immediately if no video passed the checks
+    if not checked_videos:
+        return downloaded_subtitles
+
+    # download best subtitles
+    with pool_class(**kwargs) as pool:
+        for video in checked_videos:
+            logger.info('Downloading best subtitles for %r', video)
+            subtitles = pool.download_best_subtitles(pool.list_subtitles(video, languages - video.subtitle_languages),
+                                                     video, languages, min_score=min_score,
+                                                     hearing_impaired=hearing_impaired, only_one=only_one,
+                                                     compute_score=compute_score)
+            logger.info('Downloaded %d subtitle(s)', len(subtitles))
+            downloaded_subtitles[video].extend(subtitles)
+
+    return downloaded_subtitles
+
+
+def save_subtitles(video, subtitles, single=False, directory=None, encoding=None):
+    """Save subtitles on filesystem.
+
+    Subtitles are saved in the order of the list. If a subtitle with a language has already been saved, other subtitles
+    with the same language are silently ignored.
+
+    The extension used is `.lang.srt` by default or `.srt` is `single` is `True`, with `lang` being the IETF code for
+    the :attr:`~subliminal.subtitle.Subtitle.language` of the subtitle.
+
+    :param video: video of the subtitles.
+    :type video: :class:`~subliminal.video.Video`
+    :param subtitles: subtitles to save.
+    :type subtitles: list of :class:`~subliminal.subtitle.Subtitle`
+    :param bool single: save a single subtitle, default is to save one subtitle per language.
+    :param str directory: path to directory where to save the subtitles, default is next to the video.
+    :param str encoding: encoding in which to save the subtitles, default is to keep original encoding.
+    :return: the saved subtitles
+    :rtype: list of :class:`~subliminal.subtitle.Subtitle`
+
+    """
+    saved_subtitles = []
+    for subtitle in subtitles:
+        # check content
+        if subtitle.content is None:
+            logger.error('Skipping subtitle %r: no content', subtitle)
+            continue
+
+        # check language
+        if subtitle.language in set(s.language for s in saved_subtitles):
+            logger.debug('Skipping subtitle %r: language already saved', subtitle)
+            continue
+
+        # create subtitle path
+        subtitle_path = get_subtitle_path(video.name, None if single else subtitle.language)
+        if directory is not None:
+            subtitle_path = os.path.join(directory, os.path.split(subtitle_path)[1])
+
+        # save content as is or in the specified encoding
+        logger.info('Saving %r to %r', subtitle, subtitle_path)
+        if encoding is None:
+            with io.open(subtitle_path, 'wb') as f:
+                f.write(subtitle.content)
+        else:
+            with io.open(subtitle_path, 'w', encoding=encoding) as f:
+                f.write(subtitle.text)
+        saved_subtitles.append(subtitle)
+
+        # check single
+        if single:
+            break
+
+    return saved_subtitles

subliminal/exceptions.py

@@ -1,32 +1,29 @@
 # -*- coding: utf-8 -*-
-# Copyright 2011-2012 Antoine Bertin <diaoulael@gmail.com>
-#
-# This file is part of subliminal.
-#
-# subliminal is free software; you can redistribute it and/or modify it under
-# the terms of the GNU Lesser General Public License as published by
-# the Free Software Foundation; either version 3 of the License, or
-# (at your option) any later version.
-#
-# subliminal is distributed in the hope that it will be useful,
-# but WITHOUT ANY WARRANTY; without even the implied warranty of
-# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
-# GNU Lesser General Public License for more details.
-#
-# You should have received a copy of the GNU Lesser General Public License
-# along with subliminal.  If not, see <http://www.gnu.org/licenses/>.
-
-
 class Error(Exception):
-    """Base class for exceptions in subliminal"""
+    """Base class for exceptions in subliminal."""
     pass
 
 
-class ServiceError(Error):
-    """"Exception raised by services"""
+class ProviderError(Error):
+    """Exception raised by providers."""
     pass
 
 
-class DownloadFailedError(Error):
-    """"Exception raised when a download task has failed in service"""
+class ConfigurationError(ProviderError):
+    """Exception raised by providers when badly configured."""
+    pass
+
+
+class AuthenticationError(ProviderError):
+    """Exception raised by providers when authentication failed."""
+    pass
+
+
+class TooManyRequests(ProviderError):
+    """Exception raised by providers when too many requests are made."""
+    pass
+
+
+class DownloadLimitExceeded(ProviderError):
+    """Exception raised by providers when download limit is exceeded."""
     pass

subliminal/extensions.py

@@ -0,0 +1,106 @@
+# -*- coding: utf-8 -*-
+from pkg_resources import EntryPoint
+
+from stevedore import ExtensionManager
+
+
+class RegistrableExtensionManager(ExtensionManager):
+    """:class:~stevedore.extensions.ExtensionManager` with support for registration.
+
+    It allows loading of internal extensions without setup and registering/unregistering additional extensions.
+
+    Loading is done in this order:
+
+    * Entry point extensions
+    * Internal extensions
+    * Registered extensions
+
+    :param str namespace: namespace argument for :class:~stevedore.extensions.ExtensionManager`.
+    :param list internal_extensions: internal extensions to use with entry point syntax.
+    :param \*\*kwargs: additional parameters for the :class:~stevedore.extensions.ExtensionManager` constructor.
+
+    """
+    def __init__(self, namespace, internal_extensions, **kwargs):
+        #: Registered extensions with entry point syntax
+        self.registered_extensions = []
+
+        #: Internal extensions with entry point syntax
+        self.internal_extensions = internal_extensions
+
+        super(RegistrableExtensionManager, self).__init__(namespace, **kwargs)
+
+    def _find_entry_points(self, namespace):
+        # copy of default extensions
+        eps = list(super(RegistrableExtensionManager, self)._find_entry_points(namespace))
+
+        # internal extensions
+        for iep in self.internal_extensions:
+            ep = EntryPoint.parse(iep)
+            if ep.name not in [e.name for e in eps]:
+                eps.append(ep)
+
+        # registered extensions
+        for rep in self.registered_extensions:
+            ep = EntryPoint.parse(rep)
+            if ep.name not in [e.name for e in eps]:
+                eps.append(ep)
+
+        return eps
+
+    def register(self, entry_point):
+        """Register an extension
+
+        :param str entry_point: extension to register (entry point syntax).
+        :raise: ValueError if already registered.
+
+        """
+        if entry_point in self.registered_extensions:
+            raise ValueError('Extension already registered')
+
+        ep = EntryPoint.parse(entry_point)
+        if ep.name in self.names():
+            raise ValueError('An extension with the same name already exist')
+
+        ext = self._load_one_plugin(ep, False, (), {}, False)
+        self.extensions.append(ext)
+        if self._extensions_by_name is not None:
+            self._extensions_by_name[ext.name] = ext
+        self.registered_extensions.insert(0, entry_point)
+
+    def unregister(self, entry_point):
+        """Unregister a provider
+
+        :param str entry_point: provider to unregister (entry point syntax).
+
+        """
+        if entry_point not in self.registered_extensions:
+            raise ValueError('Extension not registered')
+
+        ep = EntryPoint.parse(entry_point)
+        self.registered_extensions.remove(entry_point)
+        if self._extensions_by_name is not None:
+            del self._extensions_by_name[ep.name]
+        for i, ext in enumerate(self.extensions):
+            if ext.name == ep.name:
+                del self.extensions[i]
+                break
+
+
+#: Provider manager
+provider_manager = RegistrableExtensionManager('subliminal.providers', [
+    'addic7ed = subliminal.providers.addic7ed:Addic7edProvider',
+    'legendastv = subliminal.providers.legendastv:LegendasTVProvider',
+    'opensubtitles = subliminal.providers.opensubtitles:OpenSubtitlesProvider',
+    'podnapisi = subliminal.providers.podnapisi:PodnapisiProvider',
+    'shooter = subliminal.providers.shooter:ShooterProvider',
+    'subscenter = subliminal.providers.subscenter:SubsCenterProvider',
+    'thesubdb = subliminal.providers.thesubdb:TheSubDBProvider',
+    'tvsubtitles = subliminal.providers.tvsubtitles:TVsubtitlesProvider'
+])
+
+#: Refiner manager
+refiner_manager = RegistrableExtensionManager('subliminal.refiners', [
+    'metadata = subliminal.refiners.metadata:refine',
+    'omdb = subliminal.refiners.omdb:refine',
+    'tvdb = subliminal.refiners.tvdb:refine'
+])

subliminal/infos.py

@@ -1,18 +0,0 @@
-# -*- coding: utf-8 -*-
-# Copyright 2011-2012 Antoine Bertin <diaoulael@gmail.com>
-#
-# This file is part of subliminal.
-#
-# subliminal is free software; you can redistribute it and/or modify it under
-# the terms of the GNU Lesser General Public License as published by
-# the Free Software Foundation; either version 3 of the License, or
-# (at your option) any later version.
-#
-# subliminal is distributed in the hope that it will be useful,
-# but WITHOUT ANY WARRANTY; without even the implied warranty of
-# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
-# GNU Lesser General Public License for more details.
-#
-# You should have received a copy of the GNU Lesser General Public License
-# along with subliminal.  If not, see <http://www.gnu.org/licenses/>.
-__version__ = '0.6.1'

subliminal/providers/__init__.py

@@ -0,0 +1,161 @@
+# -*- coding: utf-8 -*-
+import logging
+
+from bs4 import BeautifulSoup, FeatureNotFound
+from six.moves.xmlrpc_client import SafeTransport
+
+from ..video import Episode, Movie
+
+logger = logging.getLogger(__name__)
+
+
+class TimeoutSafeTransport(SafeTransport):
+    """Timeout support for ``xmlrpc.client.SafeTransport``."""
+    def __init__(self, timeout, *args, **kwargs):
+        SafeTransport.__init__(self, *args, **kwargs)
+        self.timeout = timeout
+
+    def make_connection(self, host):
+        c = SafeTransport.make_connection(self, host)
+        c.timeout = self.timeout
+
+        return c
+
+
+class ParserBeautifulSoup(BeautifulSoup):
+    """A ``bs4.BeautifulSoup`` that picks the first parser available in `parsers`.
+
+    :param markup: markup for the ``bs4.BeautifulSoup``.
+    :param list parsers: parser names, in order of preference.
+
+    """
+    def __init__(self, markup, parsers, **kwargs):
+        # reject features
+        if set(parsers).intersection({'fast', 'permissive', 'strict', 'xml', 'html', 'html5'}):
+            raise ValueError('Features not allowed, only parser names')
+
+        # reject some kwargs
+        if 'features' in kwargs:
+            raise ValueError('Cannot use features kwarg')
+        if 'builder' in kwargs:
+            raise ValueError('Cannot use builder kwarg')
+
+        # pick the first parser available
+        for parser in parsers:
+            try:
+                super(ParserBeautifulSoup, self).__init__(markup, parser, **kwargs)
+                return
+            except FeatureNotFound:
+                pass
+
+        raise FeatureNotFound
+
+
+class Provider(object):
+    """Base class for providers.
+
+    If any configuration is possible for the provider, like credentials, it must take place during instantiation.
+
+    :raise: :class:`~subliminal.exceptions.ConfigurationError` if there is a configuration error
+
+    """
+    #: Supported set of :class:`~babelfish.language.Language`
+    languages = set()
+
+    #: Supported video types
+    video_types = (Episode, Movie)
+
+    #: Required hash, if any
+    required_hash = None
+
+    def __enter__(self):
+        self.initialize()
+        return self
+
+    def __exit__(self, exc_type, exc_value, traceback):
+        self.terminate()
+
+    def initialize(self):
+        """Initialize the provider.
+
+        Must be called when starting to work with the provider. This is the place for network initialization
+        or login operations.
+
+        .. note::
+            This is called automatically when entering the `with` statement
+
+        """
+        raise NotImplementedError
+
+    def terminate(self):
+        """Terminate the provider.
+
+        Must be called when done with the provider. This is the place for network shutdown or logout operations.
+
+        .. note::
+            This is called automatically when exiting the `with` statement
+
+        """
+        raise NotImplementedError
+
+    @classmethod
+    def check(cls, video):
+        """Check if the `video` can be processed.
+
+        The `video` is considered invalid if not an instance of :attr:`video_types` or if the :attr:`required_hash` is
+        not present in :attr:`~subliminal.video.Video.hashes` attribute of the `video`.
+
+        :param video: the video to check.
+        :type video: :class:`~subliminal.video.Video`
+        :return: `True` if the `video` is valid, `False` otherwise.
+        :rtype: bool
+
+        """
+        if not isinstance(video, cls.video_types):
+            return False
+        if cls.required_hash is not None and cls.required_hash not in video.hashes:
+            return False
+
+        return True
+
+    def query(self, *args, **kwargs):
+        """Query the provider for subtitles.
+
+        Arguments should match as much as possible the actual parameters for querying the provider
+
+        :return: found subtitles.
+        :rtype: list of :class:`~subliminal.subtitle.Subtitle`
+        :raise: :class:`~subliminal.exceptions.ProviderError`
+
+        """
+        raise NotImplementedError
+
+    def list_subtitles(self, video, languages):
+        """List subtitles for the `video` with the given `languages`.
+
+        This will call the :meth:`query` method internally. The parameters passed to the :meth:`query` method may
+        vary depending on the amount of information available in the `video`.
+
+        :param video: video to list subtitles for.
+        :type video: :class:`~subliminal.video.Video`
+        :param languages: languages to search for.
+        :type languages: set of :class:`~babelfish.language.Language`
+        :return: found subtitles.
+        :rtype: list of :class:`~subliminal.subtitle.Subtitle`
+        :raise: :class:`~subliminal.exceptions.ProviderError`
+
+        """
+        raise NotImplementedError
+
+    def download_subtitle(self, subtitle):
+        """Download `subtitle`'s :attr:`~subliminal.subtitle.Subtitle.content`.
+
+        :param subtitle: subtitle to download.
+        :type subtitle: :class:`~subliminal.subtitle.Subtitle`
+        :raise: :class:`~subliminal.exceptions.ProviderError`
+
+        """
+        raise NotImplementedError
+
+    def __repr__(self):
+        return '<%s [%r]>' % (self.__class__.__name__, self.video_types)

subliminal/providers/addic7ed.py

@@ -0,0 +1,285 @@
+# -*- coding: utf-8 -*-
+import logging
+import re
+
+from babelfish import Language, language_converters
+from guessit import guessit
+from requests import Session
+
+from . import ParserBeautifulSoup, Provider
+from .. import __short_version__
+from ..cache import SHOW_EXPIRATION_TIME, region
+from ..exceptions import AuthenticationError, ConfigurationError, DownloadLimitExceeded, TooManyRequests
+from ..subtitle import Subtitle, fix_line_ending, guess_matches
+from ..utils import sanitize, sanitize_release_group
+from ..video import Episode
+
+logger = logging.getLogger(__name__)
+
+language_converters.register('addic7ed = subliminal.converters.addic7ed:Addic7edConverter')
+
+#: Series header parsing regex
+series_year_re = re.compile(r'^(?P<series>[ \w\'.:-]+)(?: \((?P<year>\d{4})\))?$')
+
+
+class Addic7edSubtitle(Subtitle):
+    """Addic7ed Subtitle."""
+    provider_name = 'addic7ed'
+
+    def __init__(self, language, hearing_impaired, page_link, series, season, episode, title, year, version,
+                 download_link):
+        super(Addic7edSubtitle, self).__init__(language, hearing_impaired, page_link)
+        self.series = series
+        self.season = season
+        self.episode = episode
+        self.title = title
+        self.year = year
+        self.version = version
+        self.download_link = download_link
+
+    @property
+    def id(self):
+        return self.download_link
+
+    def get_matches(self, video):
+        matches = set()
+
+        # series
+        if video.series and sanitize(self.series) == sanitize(video.series):
+            matches.add('series')
+        # season
+        if video.season and self.season == video.season:
+            matches.add('season')
+        # episode
+        if video.episode and self.episode == video.episode:
+            matches.add('episode')
+        # title
+        if video.title and sanitize(self.title) == sanitize(video.title):
+            matches.add('title')
+        # year
+        if video.original_series and self.year is None or video.year and video.year == self.year:
+            matches.add('year')
+        # release_group
+        if (video.release_group and self.version and
+                sanitize_release_group(video.release_group) in sanitize_release_group(self.version)):
+            matches.add('release_group')
+        # resolution
+        if video.resolution and self.version and video.resolution in self.version.lower():
+            matches.add('resolution')
+        # format
+        if video.format and self.version and video.format.lower() in self.version.lower():
+            matches.add('format')
+        # other properties
+        matches |= guess_matches(video, guessit(self.version), partial=True)
+
+        return matches
+
+
+class Addic7edProvider(Provider):
+    """Addic7ed Provider."""
+    languages = {Language('por', 'BR')} | {Language(l) for l in [
+        'ara', 'aze', 'ben', 'bos', 'bul', 'cat', 'ces', 'dan', 'deu', 'ell', 'eng', 'eus', 'fas', 'fin', 'fra', 'glg',
+        'heb', 'hrv', 'hun', 'hye', 'ind', 'ita', 'jpn', 'kor', 'mkd', 'msa', 'nld', 'nor', 'pol', 'por', 'ron', 'rus',
+        'slk', 'slv', 'spa', 'sqi', 'srp', 'swe', 'tha', 'tur', 'ukr', 'vie', 'zho'
+    ]}
+    video_types = (Episode,)
+    server_url = 'http://www.addic7ed.com/'
+
+    def __init__(self, username=None, password=None):
+        if username is not None and password is None or username is None and password is not None:
+            raise ConfigurationError('Username and password must be specified')
+
+        self.username = username
+        self.password = password
+        self.logged_in = False
+
+    def initialize(self):
+        self.session = Session()
+        self.session.headers['User-Agent'] = 'Subliminal/%s' % __short_version__
+
+        # login
+        if self.username is not None and self.password is not None:
+            logger.info('Logging in')
+            data = {'username': self.username, 'password': self.password, 'Submit': 'Log in'}
+            r = self.session.post(self.server_url + 'dologin.php', data, allow_redirects=False, timeout=10)
+
+            if r.status_code != 302:
+                raise AuthenticationError(self.username)
+
+            logger.debug('Logged in')
+            self.logged_in = True
+
+    def terminate(self):
+        # logout
+        if self.logged_in:
+            logger.info('Logging out')
+            r = self.session.get(self.server_url + 'logout.php', timeout=10)
+            r.raise_for_status()
+            logger.debug('Logged out')
+            self.logged_in = False
+
+        self.session.close()
+
+    @region.cache_on_arguments(expiration_time=SHOW_EXPIRATION_TIME)
+    def _get_show_ids(self):
+        """Get the ``dict`` of show ids per series by querying the `shows.php` page.
+
+        :return: show id per series, lower case and without quotes.
+        :rtype: dict
+
+        """
+        # get the show page
+        logger.info('Getting show ids')
+        r = self.session.get(self.server_url + 'shows.php', timeout=10)
+        r.raise_for_status()
+        soup = ParserBeautifulSoup(r.content, ['lxml', 'html.parser'])
+
+        # populate the show ids
+        show_ids = {}
+        for show in soup.select('td.version > h3 > a[href^="/show/"]'):
+            show_ids[sanitize(show.text)] = int(show['href'][6:])
+        logger.debug('Found %d show ids', len(show_ids))
+
+        return show_ids
+
+    @region.cache_on_arguments(expiration_time=SHOW_EXPIRATION_TIME)
+    def _search_show_id(self, series, year=None):
+        """Search the show id from the `series` and `year`.
+
+        :param str series: series of the episode.
+        :param year: year of the series, if any.
+        :type year: int
+        :return: the show id, if found.
+        :rtype: int
+
+        """
+        # addic7ed doesn't support search with quotes
+        series = series.replace('\'', ' ')
+
+        # build the params
+        series_year = '%s %d' % (series, year) if year is not None else series
+        params = {'search': series_year, 'Submit': 'Search'}
+
+        # make the search
+        logger.info('Searching show ids with %r', params)
+        r = self.session.get(self.server_url + 'search.php', params=params, timeout=10)
+        r.raise_for_status()
+        if r.status_code == 304:
+            raise TooManyRequests()
+        soup = ParserBeautifulSoup(r.content, ['lxml', 'html.parser'])
+
+        # get the suggestion
+        suggestion = soup.select('span.titulo > a[href^="/show/"]')
+        if not suggestion:
+            logger.warning('Show id not found: no suggestion')
+            return None
+        if not sanitize(suggestion[0].i.text.replace('\'', ' ')) == sanitize(series_year):
+            logger.warning('Show id not found: suggestion does not match')
+            return None
+        show_id = int(suggestion[0]['href'][6:])
+        logger.debug('Found show id %d', show_id)
+
+        return show_id
+
+    def get_show_id(self, series, year=None, country_code=None):
+        """Get the best matching show id for `series`, `year` and `country_code`.
+
+        First search in the result of :meth:`_get_show_ids` and fallback on a search with :meth:`_search_show_id`.
+
+        :param str series: series of the episode.
+        :param year: year of the series, if any.
+        :type year: int
+        :param country_code: country code of the series, if any.
+        :type country_code: str
+        :return: the show id, if found.
+        :rtype: int
+
+        """
+        series_sanitized = sanitize(series).lower()
+        show_ids = self._get_show_ids()
+        show_id = None
+
+        # attempt with country
+        if not show_id and country_code:
+            logger.debug('Getting show id with country')
+            show_id = show_ids.get('%s %s' % (series_sanitized, country_code.lower()))
+
+        # attempt with year
+        if not show_id and year:
+            logger.debug('Getting show id with year')
+            show_id = show_ids.get('%s %d' % (series_sanitized, year))
+
+        # attempt clean
+        if not show_id:
+            logger.debug('Getting show id')
+            show_id = show_ids.get(series_sanitized)
+
+        # search as last resort
+        if not show_id:
+            logger.warning('Series not found in show ids')
+            show_id = self._search_show_id(series)
+
+        return show_id
+
+    def query(self, series, season, year=None, country=None):
+        # get the show id
+        show_id = self.get_show_id(series, year, country)
+        if show_id is None:
+            logger.error('No show id found for %r (%r)', series, {'year': year, 'country': country})
+            return []
+
+        # get the page of the season of the show
+        logger.info('Getting the page of show id %d, season %d', show_id, season)
+        r = self.session.get(self.server_url + 'show/%d' % show_id, params={'season': season}, timeout=10)
+        r.raise_for_status()
+        if r.status_code == 304:
+            raise TooManyRequests()
+        soup = ParserBeautifulSoup(r.content, ['lxml', 'html.parser'])
+
+        # loop over subtitle rows
+        match = series_year_re.match(soup.select('#header font')[0].text.strip()[:-10])
+        series = match.group('series')
+        year = int(match.group('year')) if match.group('year') else None
+        subtitles = []
+        for row in soup.select('tr.epeven'):
+            cells = row('td')
+
+            # ignore incomplete subtitles
+            status = cells[5].text
+            if status != 'Completed':
+                logger.debug('Ignoring subtitle with status %s', status)
+                continue
+
+            # read the item
+            language = Language.fromaddic7ed(cells[3].text)
+            hearing_impaired = bool(cells[6].text)
+            page_link = self.server_url + cells[2].a['href'][1:]
+            season = int(cells[0].text)
+            episode = int(cells[1].text)
+            title = cells[2].text
+            version = cells[4].text
+            download_link = cells[9].a['href'][1:]
+
+            subtitle = Addic7edSubtitle(language, hearing_impaired, page_link, series, season, episode, title, year,
+                                        version, download_link)
+            logger.debug('Found subtitle %r', subtitle)
+            subtitles.append(subtitle)
+
+        return subtitles
+
+    def list_subtitles(self, video, languages):
+        return [s for s in self.query(video.series, video.season, video.year)
+                if s.language in languages and s.episode == video.episode]
+
+    def download_subtitle(self, subtitle):
+        # download the subtitle
+        logger.info('Downloading subtitle %r', subtitle)
+        r = self.session.get(self.server_url + subtitle.download_link, headers={'Referer': subtitle.page_link},
+                             timeout=10)
+        r.raise_for_status()
+
+        # detect download limit exceeded
+        if r.headers['Content-Type'] == 'text/html':
+            raise DownloadLimitExceeded
+
+        subtitle.content = fix_line_ending(r.content)

subliminal/providers/legendastv.py

@@ -0,0 +1,448 @@
+# -*- coding: utf-8 -*-
+import io
+import json
+import logging
+import os
+import re
+
+from babelfish import Language, language_converters
+from datetime import datetime, timedelta
+from dogpile.cache.api import NO_VALUE
+from guessit import guessit
+import pytz
+import rarfile
+from rarfile import RarFile, is_rarfile
+from requests import Session
+from zipfile import ZipFile, is_zipfile
+
+from . import ParserBeautifulSoup, Provider
+from .. import __short_version__
+from ..cache import SHOW_EXPIRATION_TIME, region
+from ..exceptions import AuthenticationError, ConfigurationError, ProviderError
+from ..subtitle import SUBTITLE_EXTENSIONS, Subtitle, fix_line_ending, guess_matches, sanitize
+from ..video import Episode, Movie
+
+logger = logging.getLogger(__name__)
+
+language_converters.register('legendastv = subliminal.converters.legendastv:LegendasTVConverter')
+
+# Configure :mod:`rarfile` to use the same path separator as :mod:`zipfile`
+rarfile.PATH_SEP = '/'
+
+#: Conversion map for types
+type_map = {'M': 'movie', 'S': 'episode', 'C': 'episode'}
+
+#: BR title season parsing regex
+season_re = re.compile(r' - (?P<season>\d+)(\xaa|a|st|nd|rd|th) (temporada|season)', re.IGNORECASE)
+
+#: Downloads parsing regex
+downloads_re = re.compile(r'(?P<downloads>\d+) downloads')
+
+#: Rating parsing regex
+rating_re = re.compile(r'nota (?P<rating>\d+)')
+
+#: Timestamp parsing regex
+timestamp_re = re.compile(r'(?P<day>\d+)/(?P<month>\d+)/(?P<year>\d+) - (?P<hour>\d+):(?P<minute>\d+)')
+
+#: Cache key for releases
+releases_key = __name__ + ':releases|{archive_id}'
+
+
+class LegendasTVArchive(object):
+    """LegendasTV Archive.
+
+    :param str id: identifier.
+    :param str name: name.
+    :param bool pack: contains subtitles for multiple episodes.
+    :param bool pack: featured.
+    :param str link: link.
+    :param int downloads: download count.
+    :param int rating: rating (0-10).
+    :param timestamp: timestamp.
+    :type timestamp: datetime.datetime
+
+    """
+    def __init__(self, id, name, pack, featured, link, downloads=0, rating=0, timestamp=None):
+        #: Identifier
+        self.id = id
+
+        #: Name
+        self.name = name
+
+        #: Pack
+        self.pack = pack
+
+        #: Featured
+        self.featured = featured
+
+        #: Link
+        self.link = link
+
+        #: Download count
+        self.downloads = downloads
+
+        #: Rating (0-10)
+        self.rating = rating
+
+        #: Timestamp
+        self.timestamp = timestamp
+
+        #: Compressed content as :class:`rarfile.RarFile` or :class:`zipfile.ZipFile`
+        self.content = None
+
+    def __repr__(self):
+        return '<%s [%s] %r>' % (self.__class__.__name__, self.id, self.name)
+
+
+class LegendasTVSubtitle(Subtitle):
+    """LegendasTV Subtitle."""
+    provider_name = 'legendastv'
+
+    def __init__(self, language, type, title, year, imdb_id, season, archive, name):
+        super(LegendasTVSubtitle, self).__init__(language, archive.link)
+        self.type = type
+        self.title = title
+        self.year = year
+        self.imdb_id = imdb_id
+        self.season = season
+        self.archive = archive
+        self.name = name
+
+    @property
+    def id(self):
+        return '%s-%s' % (self.archive.id, self.name.lower())
+
+    def get_matches(self, video, hearing_impaired=False):
+        matches = set()
+
+        # episode
+        if isinstance(video, Episode) and self.type == 'episode':
+            # series
+            if video.series and sanitize(self.title) == sanitize(video.series):
+                matches.add('series')
+
+            # year (year is based on season air date hence the adjustment)
+            if video.original_series and self.year is None or video.year and video.year == self.year - self.season + 1:
+                matches.add('year')
+
+            # imdb_id
+            if video.series_imdb_id and self.imdb_id == video.series_imdb_id:
+                matches.add('series_imdb_id')
+
+        # movie
+        elif isinstance(video, Movie) and self.type == 'movie':
+            # title
+            if video.title and sanitize(self.title) == sanitize(video.title):
+                matches.add('title')
+
+            # year
+            if video.year and self.year == video.year:
+                matches.add('year')
+
+            # imdb_id
+            if video.imdb_id and self.imdb_id == video.imdb_id:
+                matches.add('imdb_id')
+
+        # archive name
+        matches |= guess_matches(video, guessit(self.archive.name, {'type': self.type}))
+
+        # name
+        matches |= guess_matches(video, guessit(self.name, {'type': self.type}))
+
+        return matches
+
+
+class LegendasTVProvider(Provider):
+    """LegendasTV Provider.
+
+    :param str username: username.
+    :param str password: password.
+
+    """
+    languages = {Language.fromlegendastv(l) for l in language_converters['legendastv'].codes}
+    server_url = 'http://legendas.tv/'
+
+    def __init__(self, username=None, password=None):
+        if username and not password or not username and password:
+            raise ConfigurationError('Username and password must be specified')
+
+        self.username = username
+        self.password = password
+        self.logged_in = False
+
+    def initialize(self):
+        self.session = Session()
+        self.session.headers['User-Agent'] = 'Subliminal/%s' % __short_version__
+
+        # login
+        if self.username is not None and self.password is not None:
+            logger.info('Logging in')
+            data = {'_method': 'POST', 'data[User][username]': self.username, 'data[User][password]': self.password}
+            r = self.session.post(self.server_url + 'login', data, allow_redirects=False, timeout=10)
+            r.raise_for_status()
+
+            soup = ParserBeautifulSoup(r.content, ['html.parser'])
+            if soup.find('div', {'class': 'alert-error'}, string=re.compile(u'Usuário ou senha inválidos')):
+                raise AuthenticationError(self.username)
+
+            logger.debug('Logged in')
+            self.logged_in = True
+
+    def terminate(self):
+        # logout
+        if self.logged_in:
+            logger.info('Logging out')
+            r = self.session.get(self.server_url + 'users/logout', allow_redirects=False, timeout=10)
+            r.raise_for_status()
+            logger.debug('Logged out')
+            self.logged_in = False
+
+        self.session.close()
+
+    @region.cache_on_arguments(expiration_time=SHOW_EXPIRATION_TIME)
+    def search_titles(self, title):
+        """Search for titles matching the `title`.
+
+        :param str title: the title to search for.
+        :return: found titles.
+        :rtype: dict
+
+        """
+        # make the query
+        logger.info('Searching title %r', title)
+        r = self.session.get(self.server_url + 'legenda/sugestao/{}'.format(title), timeout=10)
+        r.raise_for_status()
+        results = json.loads(r.text)
+
+        # loop over results
+        titles = {}
+        for result in results:
+            source = result['_source']
+
+            # extract id
+            title_id = int(source['id_filme'])
+
+            # extract type and title
+            title = {'type': type_map[source['tipo']], 'title': source['dsc_nome']}
+
+            # extract year
+            if source['dsc_data_lancamento'] and source['dsc_data_lancamento'].isdigit():
+                title['year'] = int(source['dsc_data_lancamento'])
+
+            # extract imdb_id
+            if source['id_imdb'] != '0':
+                if not source['id_imdb'].startswith('tt'):
+                    title['imdb_id'] = 'tt' + source['id_imdb'].zfill(7)
+                else:
+                    title['imdb_id'] = source['id_imdb']
+
+            # extract season
+            if title['type'] == 'episode':
+                if source['temporada'] and source['temporada'].isdigit():
+                    title['season'] = int(source['temporada'])
+                else:
+                    match = season_re.search(source['dsc_nome_br'])
+                    if match:
+                        title['season'] = int(match.group('season'))
+                    else:
+                        logger.warning('No season detected for title %d', title_id)
+
+            # add title
+            titles[title_id] = title
+
+        logger.debug('Found %d titles', len(titles))
+
+        return titles
+
+    @region.cache_on_arguments(expiration_time=timedelta(minutes=15).total_seconds())
+    def get_archives(self, title_id, language_code):
+        """Get the archive list from a given `title_id` and `language_code`.
+
+        :param int title_id: title id.
+        :param int language_code: language code.
+        :return: the archives.
+        :rtype: list of :class:`LegendasTVArchive`
+
+        """
+        logger.info('Getting archives for title %d and language %d', title_id, language_code)
+        archives = []
+        page = 1
+        while True:
+            # get the archive page
+            url = self.server_url + 'util/carrega_legendas_busca_filme/{title}/{language}/-/{page}'.format(
+                title=title_id, language=language_code, page=page)
+            r = self.session.get(url)
+            r.raise_for_status()
+
+            # parse the results
+            soup = ParserBeautifulSoup(r.content, ['lxml', 'html.parser'])
+            for archive_soup in soup.select('div.list_element > article > div'):
+                # create archive
+                archive = LegendasTVArchive(archive_soup.a['href'].split('/')[2], archive_soup.a.text,
+                                            'pack' in archive_soup['class'], 'destaque' in archive_soup['class'],
+                                            self.server_url + archive_soup.a['href'][1:])
+
+                # extract text containing downloads, rating and timestamp
+                data_text = archive_soup.find('p', class_='data').text
+
+                # match downloads
+                archive.downloads = int(downloads_re.search(data_text).group('downloads'))
+
+                # match rating
+                match = rating_re.search(data_text)
+                if match:
+                    archive.rating = int(match.group('rating'))
+
+                # match timestamp and validate it
+                time_data = {k: int(v) for k, v in timestamp_re.search(data_text).groupdict().items()}
+                archive.timestamp = pytz.timezone('America/Sao_Paulo').localize(datetime(**time_data))
+                if archive.timestamp > datetime.utcnow().replace(tzinfo=pytz.utc):
+                    raise ProviderError('Archive timestamp is in the future')
+
+                # add archive
+                archives.append(archive)
+
+            # stop on last page
+            if soup.find('a', attrs={'class': 'load_more'}, string='carregar mais') is None:
+                break
+
+            # increment page count
+            page += 1
+
+        logger.debug('Found %d archives', len(archives))
+
+        return archives
+
+    def download_archive(self, archive):
+        """Download an archive's :attr:`~LegendasTVArchive.content`.
+
+        :param archive: the archive to download :attr:`~LegendasTVArchive.content` of.
+        :type archive: :class:`LegendasTVArchive`
+
+        """
+        logger.info('Downloading archive %s', archive.id)
+        r = self.session.get(self.server_url + 'downloadarquivo/{}'.format(archive.id))
+        r.raise_for_status()
+
+        # open the archive
+        archive_stream = io.BytesIO(r.content)
+        if is_rarfile(archive_stream):
+            logger.debug('Identified rar archive')
+            archive.content = RarFile(archive_stream)
+        elif is_zipfile(archive_stream):
+            logger.debug('Identified zip archive')
+            archive.content = ZipFile(archive_stream)
+        else:
+            raise ValueError('Not a valid archive')
+
+    def query(self, language, title, season=None, episode=None, year=None):
+        # search for titles
+        titles = self.search_titles(sanitize(title))
+
+        # search for titles with the quote or dot character
+        ignore_characters = {'\'', '.'}
+        if any(c in title for c in ignore_characters):
+            titles.update(self.search_titles(sanitize(title, ignore_characters=ignore_characters)))
+
+        subtitles = []
+        # iterate over titles
+        for title_id, t in titles.items():
+            # discard mismatches on title
+            if sanitize(t['title']) != sanitize(title):
+                continue
+
+            # episode
+            if season and episode:
+                # discard mismatches on type
+                if t['type'] != 'episode':
+                    continue
+
+                # discard mismatches on season
+                if 'season' not in t or t['season'] != season:
+                    continue
+            # movie
+            else:
+                # discard mismatches on type
+                if t['type'] != 'movie':
+                    continue
+
+                # discard mismatches on year
+                if year is not None and 'year' in t and t['year'] != year:
+                    continue
+
+            # iterate over title's archives
+            for a in self.get_archives(title_id, language.legendastv):
+                # clean name of path separators and pack flags
+                clean_name = a.name.replace('/', '-')
+                if a.pack and clean_name.startswith('(p)'):
+                    clean_name = clean_name[3:]
+
+                # guess from name
+                guess = guessit(clean_name, {'type': t['type']})
+
+                # episode
+                if season and episode:
+                    # discard mismatches on episode in non-pack archives
+                    if not a.pack and 'episode' in guess and guess['episode'] != episode:
+                        continue
+
+                # compute an expiration time based on the archive timestamp
+                expiration_time = (datetime.utcnow().replace(tzinfo=pytz.utc) - a.timestamp).total_seconds()
+
+                # attempt to get the releases from the cache
+                releases = region.get(releases_key.format(archive_id=a.id), expiration_time=expiration_time)
+
+                # the releases are not in cache or cache is expired
+                if releases == NO_VALUE:
+                    logger.info('Releases not found in cache')
+
+                    # download archive
+                    self.download_archive(a)
+
+                    # extract the releases
+                    releases = []
+                    for name in a.content.namelist():
+                        # discard the legendastv file
+                        if name.startswith('Legendas.tv'):
+                            continue
+
+                        # discard hidden files
+                        if os.path.split(name)[-1].startswith('.'):
+                            continue
+
+                        # discard non-subtitle files
+                        if not name.lower().endswith(SUBTITLE_EXTENSIONS):
+                            continue
+
+                        releases.append(name)
+
+                    # cache the releases
+                    region.set(releases_key.format(archive_id=a.id), releases)
+
+                # iterate over releases
+                for r in releases:
+                    subtitle = LegendasTVSubtitle(language, t['type'], t['title'], t.get('year'), t.get('imdb_id'),
+                                                  t.get('season'), a, r)
+                    logger.debug('Found subtitle %r', subtitle)
+                    subtitles.append(subtitle)
+
+        return subtitles
+
+    def list_subtitles(self, video, languages):
+        season = episode = None
+        if isinstance(video, Episode):
+            title = video.series
+            season = video.season
+            episode = video.episode
+        else:
+            title = video.title
+
+        return [s for l in languages for s in self.query(l, title, season=season, episode=episode, year=video.year)]
+
+    def download_subtitle(self, subtitle):
+        # download archive in case we previously hit the releases cache and didn't download it
+        if subtitle.archive.content is None:
+            self.download_archive(subtitle.archive)
+
+        # extract subtitle's content
+        subtitle.content = fix_line_ending(subtitle.archive.content.read(subtitle.name))

subliminal/providers/napiprojekt.py

@@ -0,0 +1,103 @@
+# -*- coding: utf-8 -*-
+import logging
+
+from babelfish import Language
+from requests import Session
+
+from . import Provider
+from .. import __short_version__
+from ..subtitle import Subtitle
+
+logger = logging.getLogger(__name__)
+
+
+def get_subhash(hash):
+    """Get a second hash based on napiprojekt's hash.
+
+    :param str hash: napiprojekt's hash.
+    :return: the subhash.
+    :rtype: str
+
+    """
+    idx = [0xe, 0x3, 0x6, 0x8, 0x2]
+    mul = [2, 2, 5, 4, 3]
+    add = [0, 0xd, 0x10, 0xb, 0x5]
+
+    b = []
+    for i in range(len(idx)):
+        a = add[i]
+        m = mul[i]
+        i = idx[i]
+        t = a + int(hash[i], 16)
+        v = int(hash[t:t + 2], 16)
+        b.append(('%x' % (v * m))[-1])
+
+    return ''.join(b)
+
+
+class NapiProjektSubtitle(Subtitle):
+    """NapiProjekt Subtitle."""
+    provider_name = 'napiprojekt'
+
+    def __init__(self, language, hash):
+        super(NapiProjektSubtitle, self).__init__(language)
+        self.hash = hash
+
+    @property
+    def id(self):
+        return self.hash
+
+    def get_matches(self, video):
+        matches = set()
+
+        # hash
+        if 'napiprojekt' in video.hashes and video.hashes['napiprojekt'] == self.hash:
+            matches.add('hash')
+
+        return matches
+
+
+class NapiProjektProvider(Provider):
+    """NapiProjekt Provider."""
+    languages = {Language.fromalpha2(l) for l in ['pl']}
+    required_hash = 'napiprojekt'
+    server_url = 'http://napiprojekt.pl/unit_napisy/dl.php'
+
+    def initialize(self):
+        self.session = Session()
+        self.session.headers['User-Agent'] = 'Subliminal/%s' % __short_version__
+
+    def terminate(self):
+        self.session.close()
+
+    def query(self, language, hash):
+        params = {
+            'v': 'dreambox',
+            'kolejka': 'false',
+            'nick': '',
+            'pass': '',
+            'napios': 'Linux',
+            'l': language.alpha2.upper(),
+            'f': hash,
+            't': get_subhash(hash)}
+        logger.info('Searching subtitle %r', params)
+        response = self.session.get(self.server_url, params=params, timeout=10)
+        response.raise_for_status()
+
+        # handle subtitles not found and errors
+        if response.content[:4] == b'NPc0':
+            logger.debug('No subtitles found')
+            return None
+
+        subtitle = NapiProjektSubtitle(language, hash)
+        subtitle.content = response.content
+        logger.debug('Found subtitle %r', subtitle)
+
+        return subtitle
+
+    def list_subtitles(self, video, languages):
+        return [s for s in [self.query(l, video.hashes['napiprojekt']) for l in languages] if s is not None]
+
+    def download_subtitle(self, subtitle):
+        # there is no download step, content is already filled from listing subtitles
+        pass

subliminal/providers/opensubtitles.py

@@ -0,0 +1,294 @@
+# -*- coding: utf-8 -*-
+import base64
+import logging
+import os
+import re
+import zlib
+
+from babelfish import Language, language_converters
+from guessit import guessit
+from six.moves.xmlrpc_client import ServerProxy
+
+from . import Provider, TimeoutSafeTransport
+from .. import __short_version__
+from ..exceptions import AuthenticationError, ConfigurationError, DownloadLimitExceeded, ProviderError
+from ..subtitle import Subtitle, fix_line_ending, guess_matches
+from ..utils import sanitize
+from ..video import Episode, Movie
+
+logger = logging.getLogger(__name__)
+
+
+class OpenSubtitlesSubtitle(Subtitle):
+    """OpenSubtitles Subtitle."""
+    provider_name = 'opensubtitles'
+    series_re = re.compile(r'^"(?P<series_name>.*)" (?P<series_title>.*)$')
+
+    def __init__(self, language, hearing_impaired, page_link, subtitle_id, matched_by, movie_kind, hash, movie_name,
+                 movie_release_name, movie_year, movie_imdb_id, series_season, series_episode, filename, encoding):
+        super(OpenSubtitlesSubtitle, self).__init__(language, hearing_impaired, page_link, encoding)
+        self.subtitle_id = subtitle_id
+        self.matched_by = matched_by
+        self.movie_kind = movie_kind
+        self.hash = hash
+        self.movie_name = movie_name
+        self.movie_release_name = movie_release_name
+        self.movie_year = movie_year
+        self.movie_imdb_id = movie_imdb_id
+        self.series_season = series_season
+        self.series_episode = series_episode
+        self.filename = filename
+
+    @property
+    def id(self):
+        return str(self.subtitle_id)
+
+    @property
+    def series_name(self):
+        return self.series_re.match(self.movie_name).group('series_name')
+
+    @property
+    def series_title(self):
+        return self.series_re.match(self.movie_name).group('series_title')
+
+    def get_matches(self, video):
+        matches = set()
+
+        # episode
+        if isinstance(video, Episode) and self.movie_kind == 'episode':
+            # tag match, assume series, year, season and episode matches
+            if self.matched_by == 'tag':
+                matches |= {'series', 'year', 'season', 'episode'}
+            # series
+            if video.series and sanitize(self.series_name) == sanitize(video.series):
+                matches.add('series')
+            # year
+            if video.original_series and self.movie_year is None or video.year and video.year == self.movie_year:
+                matches.add('year')
+            # season
+            if video.season and self.series_season == video.season:
+                matches.add('season')
+            # episode
+            if video.episode and self.series_episode == video.episode:
+                matches.add('episode')
+            # title
+            if video.title and sanitize(self.series_title) == sanitize(video.title):
+                matches.add('title')
+            # guess
+            matches |= guess_matches(video, guessit(self.movie_release_name, {'type': 'episode'}))
+            matches |= guess_matches(video, guessit(self.filename, {'type': 'episode'}))
+            # hash
+            if 'opensubtitles' in video.hashes and self.hash == video.hashes['opensubtitles']:
+                if 'series' in matches and 'season' in matches and 'episode' in matches:
+                    matches.add('hash')
+                else:
+                    logger.debug('Match on hash discarded')
+        # movie
+        elif isinstance(video, Movie) and self.movie_kind == 'movie':
+            # tag match, assume title and year matches
+            if self.matched_by == 'tag':
+                matches |= {'title', 'year'}
+            # title
+            if video.title and sanitize(self.movie_name) == sanitize(video.title):
+                matches.add('title')
+            # year
+            if video.year and self.movie_year == video.year:
+                matches.add('year')
+            # guess
+            matches |= guess_matches(video, guessit(self.movie_release_name, {'type': 'movie'}))
+            matches |= guess_matches(video, guessit(self.filename, {'type': 'movie'}))
+            # hash
+            if 'opensubtitles' in video.hashes and self.hash == video.hashes['opensubtitles']:
+                if 'title' in matches:
+                    matches.add('hash')
+                else:
+                    logger.debug('Match on hash discarded')
+        else:
+            logger.info('%r is not a valid movie_kind', self.movie_kind)
+            return matches
+
+        # imdb_id
+        if video.imdb_id and self.movie_imdb_id == video.imdb_id:
+            matches.add('imdb_id')
+
+        return matches
+
+
+class OpenSubtitlesProvider(Provider):
+    """OpenSubtitles Provider.
+
+    :param str username: username.
+    :param str password: password.
+
+    """
+    languages = {Language.fromopensubtitles(l) for l in language_converters['opensubtitles'].codes}
+
+    def __init__(self, username=None, password=None):
+        self.server = ServerProxy('https://api.opensubtitles.org/xml-rpc', TimeoutSafeTransport(10))
+        if username and not password or not username and password:
+            raise ConfigurationError('Username and password must be specified')
+        # None values not allowed for logging in, so replace it by ''
+        self.username = username or ''
+        self.password = password or ''
+        self.token = None
+
+    def initialize(self):
+        logger.info('Logging in')
+        response = checked(self.server.LogIn(self.username, self.password, 'eng',
+                                             'subliminal v%s' % __short_version__))
+        self.token = response['token']
+        logger.debug('Logged in with token %r', self.token)
+
+    def terminate(self):
+        logger.info('Logging out')
+        checked(self.server.LogOut(self.token))
+        self.server.close()
+        self.token = None
+        logger.debug('Logged out')
+
+    def no_operation(self):
+        logger.debug('No operation')
+        checked(self.server.NoOperation(self.token))
+
+    def query(self, languages, hash=None, size=None, imdb_id=None, query=None, season=None, episode=None, tag=None):
+        # fill the search criteria
+        criteria = []
+        if hash and size:
+            criteria.append({'moviehash': hash, 'moviebytesize': str(size)})
+        if imdb_id:
+            criteria.append({'imdbid': imdb_id[2:]})
+        if tag:
+            criteria.append({'tag': tag})
+        if query and season and episode:
+            criteria.append({'query': query.replace('\'', ''), 'season': season, 'episode': episode})
+        elif query:
+            criteria.append({'query': query.replace('\'', '')})
+        if not criteria:
+            raise ValueError('Not enough information')
+
+        # add the language
+        for criterion in criteria:
+            criterion['sublanguageid'] = ','.join(sorted(l.opensubtitles for l in languages))
+
+        # query the server
+        logger.info('Searching subtitles %r', criteria)
+        response = checked(self.server.SearchSubtitles(self.token, criteria))
+        subtitles = []
+
+        # exit if no data
+        if not response['data']:
+            logger.debug('No subtitles found')
+            return subtitles
+
+        # loop over subtitle items
+        for subtitle_item in response['data']:
+            # read the item
+            language = Language.fromopensubtitles(subtitle_item['SubLanguageID'])
+            hearing_impaired = bool(int(subtitle_item['SubHearingImpaired']))
+            page_link = subtitle_item['SubtitlesLink']
+            subtitle_id = int(subtitle_item['IDSubtitleFile'])
+            matched_by = subtitle_item['MatchedBy']
+            movie_kind = subtitle_item['MovieKind']
+            hash = subtitle_item['MovieHash']
+            movie_name = subtitle_item['MovieName']
+            movie_release_name = subtitle_item['MovieReleaseName']
+            movie_year = int(subtitle_item['MovieYear']) if subtitle_item['MovieYear'] else None
+            movie_imdb_id = 'tt' + subtitle_item['IDMovieImdb']
+            series_season = int(subtitle_item['SeriesSeason']) if subtitle_item['SeriesSeason'] else None
+            series_episode = int(subtitle_item['SeriesEpisode']) if subtitle_item['SeriesEpisode'] else None
+            filename = subtitle_item['SubFileName']
+            encoding = subtitle_item.get('SubEncoding') or None
+
+            subtitle = OpenSubtitlesSubtitle(language, hearing_impaired, page_link, subtitle_id, matched_by, movie_kind,
+                                             hash, movie_name, movie_release_name, movie_year, movie_imdb_id,
+                                             series_season, series_episode, filename, encoding)
+            logger.debug('Found subtitle %r by %s', subtitle, matched_by)
+            subtitles.append(subtitle)
+
+        return subtitles
+
+    def list_subtitles(self, video, languages):
+        season = episode = None
+        if isinstance(video, Episode):
+            query = video.series
+            season = video.season
+            episode = video.episode
+        else:
+            query = video.title
+
+        return self.query(languages, hash=video.hashes.get('opensubtitles'), size=video.size, imdb_id=video.imdb_id,
+                          query=query, season=season, episode=episode, tag=os.path.basename(video.name))
+
+    def download_subtitle(self, subtitle):
+        logger.info('Downloading subtitle %r', subtitle)
+        response = checked(self.server.DownloadSubtitles(self.token, [str(subtitle.subtitle_id)]))
+        subtitle.content = fix_line_ending(zlib.decompress(base64.b64decode(response['data'][0]['data']), 47))
+
+
+class OpenSubtitlesError(ProviderError):
+    """Base class for non-generic :class:`OpenSubtitlesProvider` exceptions."""
+    pass
+
+
+class Unauthorized(OpenSubtitlesError, AuthenticationError):
+    """Exception raised when status is '401 Unauthorized'."""
+    pass
+
+
+class NoSession(OpenSubtitlesError, AuthenticationError):
+    """Exception raised when status is '406 No session'."""
+    pass
+
+
+class DownloadLimitReached(OpenSubtitlesError, DownloadLimitExceeded):
+    """Exception raised when status is '407 Download limit reached'."""
+    pass
+
+
+class InvalidImdbid(OpenSubtitlesError):
+    """Exception raised when status is '413 Invalid ImdbID'."""
+    pass
+
+
+class UnknownUserAgent(OpenSubtitlesError, AuthenticationError):
+    """Exception raised when status is '414 Unknown User Agent'."""
+    pass
+
+
+class DisabledUserAgent(OpenSubtitlesError, AuthenticationError):
+    """Exception raised when status is '415 Disabled user agent'."""
+    pass
+
+
+class ServiceUnavailable(OpenSubtitlesError):
+    """Exception raised when status is '503 Service Unavailable'."""
+    pass
+
+
+def checked(response):
+    """Check a response status before returning it.
+
+    :param response: a response from a XMLRPC call to OpenSubtitles.
+    :return: the response.
+    :raise: :class:`OpenSubtitlesError`
+
+    """
+    status_code = int(response['status'][:3])
+    if status_code == 401:
+        raise Unauthorized
+    if status_code == 406:
+        raise NoSession
+    if status_code == 407:
+        raise DownloadLimitReached
+    if status_code == 413:
+        raise InvalidImdbid
+    if status_code == 414:
+        raise UnknownUserAgent
+    if status_code == 415:
+        raise DisabledUserAgent
+    if status_code == 503:
+        raise ServiceUnavailable
+    if status_code != 200:
+        raise OpenSubtitlesError(response['status'])
+
+    return response

subliminal/providers/podnapisi.py

@@ -0,0 +1,179 @@
+# -*- coding: utf-8 -*-
+import io
+import logging
+import re
+
+from babelfish import Language, language_converters
+from guessit import guessit
+try:
+    from lxml import etree
+except ImportError:
+    try:
+        import xml.etree.cElementTree as etree
+    except ImportError:
+        import xml.etree.ElementTree as etree
+from requests import Session
+from zipfile import ZipFile
+
+from . import Provider
+from .. import __short_version__
+from ..exceptions import ProviderError
+from ..subtitle import Subtitle, fix_line_ending, guess_matches
+from ..utils import sanitize
+from ..video import Episode, Movie
+
+logger = logging.getLogger(__name__)
+
+
+class PodnapisiSubtitle(Subtitle):
+    """Podnapisi Subtitle."""
+    provider_name = 'podnapisi'
+
+    def __init__(self, language, hearing_impaired, page_link, pid, releases, title, season=None, episode=None,
+                 year=None):
+        super(PodnapisiSubtitle, self).__init__(language, hearing_impaired, page_link)
+        self.pid = pid
+        self.releases = releases
+        self.title = title
+        self.season = season
+        self.episode = episode
+        self.year = year
+
+    @property
+    def id(self):
+        return self.pid
+
+    def get_matches(self, video):
+        matches = set()
+
+        # episode
+        if isinstance(video, Episode):
+            # series
+            if video.series and sanitize(self.title) == sanitize(video.series):
+                matches.add('series')
+            # year
+            if video.original_series and self.year is None or video.year and video.year == self.year:
+                matches.add('year')
+            # season
+            if video.season and self.season == video.season:
+                matches.add('season')
+            # episode
+            if video.episode and self.episode == video.episode:
+                matches.add('episode')
+            # guess
+            for release in self.releases:
+                matches |= guess_matches(video, guessit(release, {'type': 'episode'}))
+        # movie
+        elif isinstance(video, Movie):
+            # title
+            if video.title and sanitize(self.title) == sanitize(video.title):
+                matches.add('title')
+            # year
+            if video.year and self.year == video.year:
+                matches.add('year')
+            # guess
+            for release in self.releases:
+                matches |= guess_matches(video, guessit(release, {'type': 'movie'}))
+
+        return matches
+
+
+class PodnapisiProvider(Provider):
+    """Podnapisi Provider."""
+    languages = ({Language('por', 'BR'), Language('srp', script='Latn')} |
+                 {Language.fromalpha2(l) for l in language_converters['alpha2'].codes})
+    server_url = 'http://podnapisi.net/subtitles/'
+
+    def initialize(self):
+        self.session = Session()
+        self.session.headers['User-Agent'] = 'Subliminal/%s' % __short_version__
+
+    def terminate(self):
+        self.session.close()
+
+    def query(self, language, keyword, season=None, episode=None, year=None):
+        # set parameters, see http://www.podnapisi.net/forum/viewtopic.php?f=62&t=26164#p212652
+        params = {'sXML': 1, 'sL': str(language), 'sK': keyword}
+        is_episode = False
+        if season and episode:
+            is_episode = True
+            params['sTS'] = season
+            params['sTE'] = episode
+        if year:
+            params['sY'] = year
+
+        # loop over paginated results
+        logger.info('Searching subtitles %r', params)
+        subtitles = []
+        pids = set()
+        while True:
+            # query the server
+            xml = etree.fromstring(self.session.get(self.server_url + 'search/old', params=params, timeout=10).content)
+
+            # exit if no results
+            if not int(xml.find('pagination/results').text):
+                logger.debug('No subtitles found')
+                break
+
+            # loop over subtitles
+            for subtitle_xml in xml.findall('subtitle'):
+                # read xml elements
+                language = Language.fromietf(subtitle_xml.find('language').text)
+                hearing_impaired = 'n' in (subtitle_xml.find('flags').text or '')
+                page_link = subtitle_xml.find('url').text
+                pid = subtitle_xml.find('pid').text
+                releases = []
+                if subtitle_xml.find('release').text:
+                    for release in subtitle_xml.find('release').text.split():
+                        release = re.sub(r'\.+$', '', release)  # remove trailing dots
+                        release = ''.join(filter(lambda x: ord(x) < 128, release))  # remove non-ascii characters
+                        releases.append(release)
+                title = subtitle_xml.find('title').text
+                season = int(subtitle_xml.find('tvSeason').text)
+                episode = int(subtitle_xml.find('tvEpisode').text)
+                year = int(subtitle_xml.find('year').text)
+
+                if is_episode:
+                    subtitle = PodnapisiSubtitle(language, hearing_impaired, page_link, pid, releases, title,
+                                                 season=season, episode=episode, year=year)
+                else:
+                    subtitle = PodnapisiSubtitle(language, hearing_impaired, page_link, pid, releases, title,
+                                                 year=year)
+
+                # ignore duplicates, see http://www.podnapisi.net/forum/viewtopic.php?f=62&t=26164&start=10#p213321
+                if pid in pids:
+                    continue
+
+                logger.debug('Found subtitle %r', subtitle)
+                subtitles.append(subtitle)
+                pids.add(pid)
+
+            # stop on last page
+            if int(xml.find('pagination/current').text) >= int(xml.find('pagination/count').text):
+                break
+
+            # increment current page
+            params['page'] = int(xml.find('pagination/current').text) + 1
+            logger.debug('Getting page %d', params['page'])
+
+        return subtitles
+
+    def list_subtitles(self, video, languages):
+        if isinstance(video, Episode):
+            return [s for l in languages for s in self.query(l, video.series, season=video.season,
+                                                             episode=video.episode, year=video.year)]
+        elif isinstance(video, Movie):
+            return [s for l in languages for s in self.query(l, video.title, year=video.year)]
+
+    def download_subtitle(self, subtitle):
+        # download as a zip
+        logger.info('Downloading subtitle %r', subtitle)
+        r = self.session.get(self.server_url + subtitle.pid + '/download', params={'container': 'zip'}, timeout=10)
+        r.raise_for_status()
+
+        # open the zip
+        with ZipFile(io.BytesIO(r.content)) as zf:
+            if len(zf.namelist()) > 1:
+                raise ProviderError('More than one file to unzip')
+
+            subtitle.content = fix_line_ending(zf.read(zf.namelist()[0]))

subliminal/providers/shooter.py

@@ -0,0 +1,79 @@
+# -*- coding: utf-8 -*-
+import json
+import logging
+import os
+
+from babelfish import Language, language_converters
+from requests import Session
+
+from . import Provider
+from .. import __short_version__
+from ..subtitle import Subtitle, fix_line_ending
+
+logger = logging.getLogger(__name__)
+
+language_converters.register('shooter = subliminal.converters.shooter:ShooterConverter')
+
+
+class ShooterSubtitle(Subtitle):
+    """Shooter Subtitle."""
+    provider_name = 'shooter'
+
+    def __init__(self, language, hash, download_link):
+        super(ShooterSubtitle, self).__init__(language)
+        self.hash = hash
+        self.download_link = download_link
+
+    @property
+    def id(self):
+        return self.download_link
+
+    def get_matches(self, video):
+        matches = set()
+
+        # hash
+        if 'shooter' in video.hashes and video.hashes['shooter'] == self.hash:
+            matches.add('hash')
+
+        return matches
+
+
+class ShooterProvider(Provider):
+    """Shooter Provider."""
+    languages = {Language(l) for l in ['eng', 'zho']}
+    server_url = 'https://www.shooter.cn/api/subapi.php'
+
+    def initialize(self):
+        self.session = Session()
+        self.session.headers['User-Agent'] = 'Subliminal/%s' % __short_version__
+
+    def terminate(self):
+        self.session.close()
+
+    def query(self, language, filename, hash=None):
+        # query the server
+        params = {'filehash': hash, 'pathinfo': os.path.realpath(filename), 'format': 'json', 'lang': language.shooter}
+        logger.debug('Searching subtitles %r', params)
+        r = self.session.post(self.server_url, params=params, timeout=10)
+        r.raise_for_status()
+
+        # handle subtitles not found
+        if r.content == b'\xff':
+            logger.debug('No subtitles found')
+            return []
+
+        # parse the subtitles
+        results = json.loads(r.text)
+        subtitles = [ShooterSubtitle(language, hash, t['Link']) for s in results for t in s['Files']]
+
+        return subtitles
+
+    def list_subtitles(self, video, languages):
+        return [s for l in languages for s in self.query(l, video.name, video.hashes.get('shooter'))]
+
+    def download_subtitle(self, subtitle):
+        logger.info('Downloading subtitle %r', subtitle)
+        r = self.session.get(subtitle.download_link, timeout=10)
+        r.raise_for_status()
+
+        subtitle.content = fix_line_ending(r.content)

subliminal/providers/subscenter.py

@@ -0,0 +1,228 @@
+# -*- coding: utf-8 -*-
+import bisect
+from collections import defaultdict
+import io
+import json
+import logging
+import zipfile
+
+from babelfish import Language
+from guessit import guessit
+from requests import Session
+
+from . import ParserBeautifulSoup, Provider
+from .. import __short_version__
+from ..cache import SHOW_EXPIRATION_TIME, region
+from ..exceptions import AuthenticationError, ConfigurationError, ProviderError
+from ..subtitle import Subtitle, fix_line_ending, guess_matches
+from ..utils import sanitize
+from ..video import Episode, Movie
+
+logger = logging.getLogger(__name__)
+
+
+class SubsCenterSubtitle(Subtitle):
+    """SubsCenter Subtitle."""
+    provider_name = 'subscenter'
+
+    def __init__(self, language, hearing_impaired, page_link, series, season, episode, title, subtitle_id, subtitle_key,
+                 downloaded, releases):
+        super(SubsCenterSubtitle, self).__init__(language, hearing_impaired, page_link)
+        self.series = series
+        self.season = season
+        self.episode = episode
+        self.title = title
+        self.subtitle_id = subtitle_id
+        self.subtitle_key = subtitle_key
+        self.downloaded = downloaded
+        self.releases = releases
+
+    @property
+    def id(self):
+        return str(self.subtitle_id)
+
+    def get_matches(self, video):
+        matches = set()
+
+        # episode
+        if isinstance(video, Episode):
+            # series
+            if video.series and sanitize(self.series) == sanitize(video.series):
+                matches.add('series')
+            # season
+            if video.season and self.season == video.season:
+                matches.add('season')
+            # episode
+            if video.episode and self.episode == video.episode:
+                matches.add('episode')
+            # guess
+            for release in self.releases:
+                matches |= guess_matches(video, guessit(release, {'type': 'episode'}))
+        # movie
+        elif isinstance(video, Movie):
+            # guess
+            for release in self.releases:
+                matches |= guess_matches(video, guessit(release, {'type': 'movie'}))
+
+        # title
+        if video.title and sanitize(self.title) == sanitize(video.title):
+            matches.add('title')
+
+        return matches
+
+
+class SubsCenterProvider(Provider):
+    """SubsCenter Provider."""
+    languages = {Language.fromalpha2(l) for l in ['he']}
+    server_url = 'http://subscenter.cinemast.com/he/'
+
+    def __init__(self, username=None, password=None):
+        if username is not None and password is None or username is None and password is not None:
+            raise ConfigurationError('Username and password must be specified')
+
+        self.username = username
+        self.password = password
+        self.logged_in = False
+
+    def initialize(self):
+        self.session = Session()
+        self.session.headers['User-Agent'] = 'Subliminal/%s' % __short_version__
+
+        # login
+        if self.username is not None and self.password is not None:
+            logger.debug('Logging in')
+            url = self.server_url + 'subscenter/accounts/login/'
+
+            # retrieve CSRF token
+            self.session.get(url)
+            csrf_token = self.session.cookies['csrftoken']
+
+            # actual login
+            data = {'username': self.username, 'password': self.password, 'csrfmiddlewaretoken': csrf_token}
+            r = self.session.post(url, data, allow_redirects=False, timeout=10)
+
+            if r.status_code != 302:
+                raise AuthenticationError(self.username)
+
+            logger.info('Logged in')
+            self.logged_in = True
+
+    def terminate(self):
+        # logout
+        if self.logged_in:
+            logger.info('Logging out')
+            r = self.session.get(self.server_url + 'subscenter/accounts/logout/', timeout=10)
+            r.raise_for_status()
+            logger.info('Logged out')
+            self.logged_in = False
+
+        self.session.close()
+
+    @region.cache_on_arguments(expiration_time=SHOW_EXPIRATION_TIME)
+    def _search_url_titles(self, title):
+        """Search the URL titles by kind for the given `title`.
+
+        :param str title: title to search for.
+        :return: the URL titles by kind.
+        :rtype: collections.defaultdict
+
+        """
+        # make the search
+        logger.info('Searching title name for %r', title)
+        r = self.session.get(self.server_url + 'subtitle/search/', params={'q': title}, timeout=10)
+        r.raise_for_status()
+
+        # get the suggestions
+        soup = ParserBeautifulSoup(r.content, ['lxml', 'html.parser'])
+        links = soup.select('#processes div.generalWindowTop a')
+        logger.debug('Found %d suggestions', len(links))
+        url_titles = defaultdict(list)
+        for link in links:
+            parts = link.attrs['href'].split('/')
+            url_titles[parts[-3]].append(parts[-2])
+
+        return url_titles
+
+    def query(self, title, season=None, episode=None):
+        # search for the url title
+        url_titles = self._search_url_titles(title)
+
+        # episode
+        if season and episode:
+            if 'series' not in url_titles:
+                logger.error('No URL title found for series %r', title)
+                return []
+            url_title = url_titles['series'][0]
+            logger.debug('Using series title %r', url_title)
+            url = self.server_url + 'cinemast/data/series/sb/{}/{}/{}/'.format(url_title, season, episode)
+            page_link = self.server_url + 'subtitle/series/{}/{}/{}/'.format(url_title, season, episode)
+        else:
+            if 'movie' not in url_titles:
+                logger.error('No URL title found for movie %r', title)
+                return []
+            url_title = url_titles['movie'][0]
+            logger.debug('Using movie title %r', url_title)
+            url = self.server_url + 'cinemast/data/movie/sb/{}/'.format(url_title)
+            page_link = self.server_url + 'subtitle/movie/{}/'.format(url_title)
+
+        # get the list of subtitles
+        logger.debug('Getting the list of subtitles')
+        r = self.session.get(url)
+        r.raise_for_status()
+        results = json.loads(r.text)
+
+        # loop over results
+        subtitles = {}
+        for language_code, language_data in results.items():
+            for quality_data in language_data.values():
+                for quality, subtitles_data in quality_data.items():
+                    for subtitle_item in subtitles_data.values():
+                        # read the item
+                        language = Language.fromalpha2(language_code)
+                        hearing_impaired = bool(subtitle_item['hearing_impaired'])
+                        subtitle_id = subtitle_item['id']
+                        subtitle_key = subtitle_item['key']
+                        downloaded = subtitle_item['downloaded']
+                        release = subtitle_item['subtitle_version']
+
+                        # add the release and increment downloaded count if we already have the subtitle
+                        if subtitle_id in subtitles:
+                            logger.debug('Found additional release %r for subtitle %d', release, subtitle_id)
+                            bisect.insort_left(subtitles[subtitle_id].releases, release)  # deterministic order
+                            subtitles[subtitle_id].downloaded += downloaded
+                            continue
+
+                        # otherwise create it
+                        subtitle = SubsCenterSubtitle(language, hearing_impaired, page_link, title, season, episode,
+                                                      title, subtitle_id, subtitle_key, downloaded, [release])
+                        logger.debug('Found subtitle %r', subtitle)
+                        subtitles[subtitle_id] = subtitle
+
+        return subtitles.values()
+
+    def list_subtitles(self, video, languages):
+        season = episode = None
+        title = video.title
+
+        if isinstance(video, Episode):
+            title = video.series
+            season = video.season
+            episode = video.episode
+
+        return [s for s in self.query(title, season, episode) if s.language in languages]
+
+    def download_subtitle(self, subtitle):
+        # download
+        url = self.server_url + 'subtitle/download/{}/{}/'.format(subtitle.language.alpha2, subtitle.subtitle_id)
+        params = {'v': subtitle.releases[0], 'key': subtitle.subtitle_key}
+        r = self.session.get(url, params=params, headers={'Referer': subtitle.page_link}, timeout=10)
+        r.raise_for_status()
+
+        # open the zip
+        with zipfile.ZipFile(io.BytesIO(r.content)) as zf:
+            # remove some filenames from the namelist
+            namelist = [n for n in zf.namelist() if not n.endswith('.txt')]
+            if len(namelist) > 1:
+                raise ProviderError('More than one file to unzip')
+
+            subtitle.content = fix_line_ending(zf.read(namelist[0]))

subliminal/providers/thesubdb.py

@@ -0,0 +1,84 @@
+# -*- coding: utf-8 -*-
+import logging
+
+from babelfish import Language, language_converters
+from requests import Session
+
+from . import Provider
+from .. import __short_version__
+from ..subtitle import Subtitle, fix_line_ending
+
+logger = logging.getLogger(__name__)
+
+language_converters.register('thesubdb = subliminal.converters.thesubdb:TheSubDBConverter')
+
+
+class TheSubDBSubtitle(Subtitle):
+    """TheSubDB Subtitle."""
+    provider_name = 'thesubdb'
+
+    def __init__(self, language, hash):
+        super(TheSubDBSubtitle, self).__init__(language)
+        self.hash = hash
+
+    @property
+    def id(self):
+        return self.hash + '-' + str(self.language)
+
+    def get_matches(self, video):
+        matches = set()
+
+        # hash
+        if 'thesubdb' in video.hashes and video.hashes['thesubdb'] == self.hash:
+            matches.add('hash')
+
+        return matches
+
+
+class TheSubDBProvider(Provider):
+    """TheSubDB Provider."""
+    languages = {Language.fromthesubdb(l) for l in language_converters['thesubdb'].codes}
+    required_hash = 'thesubdb'
+    server_url = 'http://api.thesubdb.com/'
+
+    def initialize(self):
+        self.session = Session()
+        self.session.headers['User-Agent'] = ('SubDB/1.0 (subliminal/%s; https://github.com/Diaoul/subliminal)' %
+                                              __short_version__)
+
+    def terminate(self):
+        self.session.close()
+
+    def query(self, hash):
+        # make the query
+        params = {'action': 'search', 'hash': hash}
+        logger.info('Searching subtitles %r', params)
+        r = self.session.get(self.server_url, params=params, timeout=10)
+
+        # handle subtitles not found and errors
+        if r.status_code == 404:
+            logger.debug('No subtitles found')
+            return []
+        r.raise_for_status()
+
+        # loop over languages
+        subtitles = []
+        for language_code in r.text.split(','):
+            language = Language.fromthesubdb(language_code)
+
+            subtitle = TheSubDBSubtitle(language, hash)
+            logger.debug('Found subtitle %r', subtitle)
+            subtitles.append(subtitle)
+
+        return subtitles
+
+    def list_subtitles(self, video, languages):
+        return [s for s in self.query(video.hashes['thesubdb']) if s.language in languages]
+
+    def download_subtitle(self, subtitle):
+        logger.info('Downloading subtitle %r', subtitle)
+        params = {'action': 'download', 'hash': subtitle.hash, 'language': subtitle.language.alpha2}
+        r = self.session.get(self.server_url, params=params, timeout=10)
+        r.raise_for_status()
+
+        subtitle.content = fix_line_ending(r.content)

subliminal/providers/tvsubtitles.py

@@ -0,0 +1,208 @@
+# -*- coding: utf-8 -*-
+import io
+import logging
+import re
+from zipfile import ZipFile
+
+from babelfish import Language, language_converters
+from guessit import guessit
+from requests import Session
+
+from . import ParserBeautifulSoup, Provider
+from .. import __short_version__
+from ..cache import EPISODE_EXPIRATION_TIME, SHOW_EXPIRATION_TIME, region
+from ..exceptions import ProviderError
+from ..subtitle import Subtitle, fix_line_ending, guess_matches
+from ..utils import sanitize, sanitize_release_group
+from ..video import Episode
+
+logger = logging.getLogger(__name__)
+
+language_converters.register('tvsubtitles = subliminal.converters.tvsubtitles:TVsubtitlesConverter')
+
+link_re = re.compile(r'^(?P<series>.+?)(?: \(?\d{4}\)?| \((?:US|UK)\))? \((?P<first_year>\d{4})-\d{4}\)$')
+episode_id_re = re.compile(r'^episode-\d+\.html$')
+
+
+class TVsubtitlesSubtitle(Subtitle):
+    """TVsubtitles Subtitle."""
+    provider_name = 'tvsubtitles'
+
+    def __init__(self, language, page_link, subtitle_id, series, season, episode, year, rip, release):
+        super(TVsubtitlesSubtitle, self).__init__(language, page_link=page_link)
+        self.subtitle_id = subtitle_id
+        self.series = series
+        self.season = season
+        self.episode = episode
+        self.year = year
+        self.rip = rip
+        self.release = release
+
+    @property
+    def id(self):
+        return str(self.subtitle_id)
+
+    def get_matches(self, video):
+        matches = set()
+
+        # series
+        if video.series and sanitize(self.series) == sanitize(video.series):
+            matches.add('series')
+        # season
+        if video.season and self.season == video.season:
+            matches.add('season')
+        # episode
+        if video.episode and self.episode == video.episode:
+            matches.add('episode')
+        # year
+        if video.original_series and self.year is None or video.year and video.year == self.year:
+            matches.add('year')
+        # release_group
+        if (video.release_group and self.release and
+                sanitize_release_group(video.release_group) in sanitize_release_group(self.release)):
+            matches.add('release_group')
+        # other properties
+        if self.release:
+            matches |= guess_matches(video, guessit(self.release, {'type': 'episode'}), partial=True)
+        if self.rip:
+            matches |= guess_matches(video, guessit(self.rip), partial=True)
+
+        return matches
+
+
+class TVsubtitlesProvider(Provider):
+    """TVsubtitles Provider."""
+    languages = {Language('por', 'BR')} | {Language(l) for l in [
+        'ara', 'bul', 'ces', 'dan', 'deu', 'ell', 'eng', 'fin', 'fra', 'hun', 'ita', 'jpn', 'kor', 'nld', 'pol', 'por',
+        'ron', 'rus', 'spa', 'swe', 'tur', 'ukr', 'zho'
+    ]}
+    video_types = (Episode,)
+    server_url = 'http://www.tvsubtitles.net/'
+
+    def initialize(self):
+        self.session = Session()
+        self.session.headers['User-Agent'] = 'Subliminal/%s' % __short_version__
+
+    def terminate(self):
+        self.session.close()
+
+    @region.cache_on_arguments(expiration_time=SHOW_EXPIRATION_TIME)
+    def search_show_id(self, series, year=None):
+        """Search the show id from the `series` and `year`.
+
+        :param str series: series of the episode.
+        :param year: year of the series, if any.
+        :type year: int
+        :return: the show id, if any.
+        :rtype: int
+
+        """
+        # make the search
+        logger.info('Searching show id for %r', series)
+        r = self.session.post(self.server_url + 'search.php', data={'q': series}, timeout=10)
+        r.raise_for_status()
+
+        # get the series out of the suggestions
+        soup = ParserBeautifulSoup(r.content, ['lxml', 'html.parser'])
+        show_id = None
+        for suggestion in soup.select('div.left li div a[href^="/tvshow-"]'):
+            match = link_re.match(suggestion.text)
+            if not match:
+                logger.error('Failed to match %s', suggestion.text)
+                continue
+
+            if match.group('series').lower() == series.lower():
+                if year is not None and int(match.group('first_year')) != year:
+                    logger.debug('Year does not match')
+                    continue
+                show_id = int(suggestion['href'][8:-5])
+                logger.debug('Found show id %d', show_id)
+                break
+
+        return show_id
+
+    @region.cache_on_arguments(expiration_time=EPISODE_EXPIRATION_TIME)
+    def get_episode_ids(self, show_id, season):
+        """Get episode ids from the show id and the season.
+
+        :param int show_id: show id.
+        :param int season: season of the episode.
+        :return: episode ids per episode number.
+        :rtype: dict
+
+        """
+        # get the page of the season of the show
+        logger.info('Getting the page of show id %d, season %d', show_id, season)
+        r = self.session.get(self.server_url + 'tvshow-%d-%d.html' % (show_id, season), timeout=10)
+        soup = ParserBeautifulSoup(r.content, ['lxml', 'html.parser'])
+
+        # loop over episode rows
+        episode_ids = {}
+        for row in soup.select('table#table5 tr'):
+            # skip rows that do not have a link to the episode page
+            if not row('a', href=episode_id_re):
+                continue
+
+            # extract data from the cells
+            cells = row('td')
+            episode = int(cells[0].text.split('x')[1])
+            episode_id = int(cells[1].a['href'][8:-5])
+            episode_ids[episode] = episode_id
+
+        if episode_ids:
+            logger.debug('Found episode ids %r', episode_ids)
+        else:
+            logger.warning('No episode ids found')
+
+        return episode_ids
+
+    def query(self, series, season, episode, year=None):
+        # search the show id
+        show_id = self.search_show_id(series, year)
+        if show_id is None:
+            logger.error('No show id found for %r (%r)', series, {'year': year})
+            return []
+
+        # get the episode ids
+        episode_ids = self.get_episode_ids(show_id, season)
+        if episode not in episode_ids:
+            logger.error('Episode %d not found', episode)
+            return []
+
+        # get the episode page
+        logger.info('Getting the page for episode %d', episode_ids[episode])
+        r = self.session.get(self.server_url + 'episode-%d.html' % episode_ids[episode], timeout=10)
+        soup = ParserBeautifulSoup(r.content, ['lxml', 'html.parser'])
+
+        # loop over subtitles rows
+        subtitles = []
+        for row in soup.select('.subtitlen'):
+            # read the item
+            language = Language.fromtvsubtitles(row.h5.img['src'][13:-4])
+            subtitle_id = int(row.parent['href'][10:-5])
+            page_link = self.server_url + 'subtitle-%d.html' % subtitle_id
+            rip = row.find('p', title='rip').text.strip() or None
+            release = row.find('p', title='release').text.strip() or None
+
+            subtitle = TVsubtitlesSubtitle(language, page_link, subtitle_id, series, season, episode, year, rip,
+                                           release)
+            logger.debug('Found subtitle %s', subtitle)
+            subtitles.append(subtitle)
+
+        return subtitles
+
+    def list_subtitles(self, video, languages):
+        return [s for s in self.query(video.series, video.season, video.episode, video.year) if s.language in languages]
+
+    def download_subtitle(self, subtitle):
+        # download as a zip
+        logger.info('Downloading subtitle %r', subtitle)
+        r = self.session.get(self.server_url + 'download-%d.html' % subtitle.subtitle_id, timeout=10)
+        r.raise_for_status()
+
+        # open the zip
+        with ZipFile(io.BytesIO(r.content)) as zf:
+            if len(zf.namelist()) > 1:
+                raise ProviderError('More than one file to unzip')
+
+            subtitle.content = fix_line_ending(zf.read(zf.namelist()[0]))

subliminal/refiners/__init__.py

@@ -0,0 +1,12 @@
+"""
+Refiners enrich a :class:`~subliminal.video.Video` object by adding information to it.
+
+A refiner is a simple function:
+
+.. py:function:: refine(video, **kwargs)
+
+    :param video: the video to refine.
+    :type video: :class:`~subliminal.video.Video`
+    :param \*\*kwargs: additional parameters for refiners.
+
+"""

subliminal/refiners/metadata.py

@@ -0,0 +1,99 @@
+# -*- coding: utf-8 -*-
+import logging
+import os
+
+from babelfish import Error as BabelfishError, Language
+from enzyme import MKV
+
+logger = logging.getLogger(__name__)
+
+
+def refine(video, embedded_subtitles=True, **kwargs):
+    """Refine a video by searching its metadata.
+
+    Several :class:`~subliminal.video.Video` attributes can be found:
+
+      * :attr:`~subliminal.video.Video.resolution`
+      * :attr:`~subliminal.video.Video.video_codec`
+      * :attr:`~subliminal.video.Video.audio_codec`
+      * :attr:`~subliminal.video.Video.subtitle_languages`
+
+    :param bool embedded_subtitles: search for embedded subtitles.
+
+    """
+    # skip non existing videos
+    if not video.exists:
+        return
+
+    # check extensions
+    extension = os.path.splitext(video.name)[1]
+    if extension == '.mkv':
+        with open(video.name, 'rb') as f:
+            mkv = MKV(f)
+
+        # main video track
+        if mkv.video_tracks:
+            video_track = mkv.video_tracks[0]
+
+            # resolution
+            if video_track.height in (480, 720, 1080):
+                if video_track.interlaced:
+                    video.resolution = '%di' % video_track.height
+                else:
+                    video.resolution = '%dp' % video_track.height
+                logger.debug('Found resolution %s', video.resolution)
+
+            # video codec
+            if video_track.codec_id == 'V_MPEG4/ISO/AVC':
+                video.video_codec = 'h264'
+                logger.debug('Found video_codec %s', video.video_codec)
+            elif video_track.codec_id == 'V_MPEG4/ISO/SP':
+                video.video_codec = 'DivX'
+                logger.debug('Found video_codec %s', video.video_codec)
+            elif video_track.codec_id == 'V_MPEG4/ISO/ASP':
+                video.video_codec = 'XviD'
+                logger.debug('Found video_codec %s', video.video_codec)
+        else:
+            logger.warning('MKV has no video track')
+
+        # main audio track
+        if mkv.audio_tracks:
+            audio_track = mkv.audio_tracks[0]
+            # audio codec
+            if audio_track.codec_id == 'A_AC3':
+                video.audio_codec = 'AC3'
+                logger.debug('Found audio_codec %s', video.audio_codec)
+            elif audio_track.codec_id == 'A_DTS':
+                video.audio_codec = 'DTS'
+                logger.debug('Found audio_codec %s', video.audio_codec)
+            elif audio_track.codec_id == 'A_AAC':
+                video.audio_codec = 'AAC'
+                logger.debug('Found audio_codec %s', video.audio_codec)
+        else:
+            logger.warning('MKV has no audio track')
+
+        # subtitle tracks
+        if mkv.subtitle_tracks:
+            if embedded_subtitles:
+                embedded_subtitle_languages = set()
+                for st in mkv.subtitle_tracks:
+                    if st.language:
+                        try:
+                            embedded_subtitle_languages.add(Language.fromalpha3b(st.language))
+                        except BabelfishError:
+                            logger.error('Embedded subtitle track language %r is not a valid language', st.language)
+                            embedded_subtitle_languages.add(Language('und'))
+                    elif st.name:
+                        try:
+                            embedded_subtitle_languages.add(Language.fromname(st.name))
+                        except BabelfishError:
+                            logger.debug('Embedded subtitle track name %r is not a valid language', st.name)
+                            embedded_subtitle_languages.add(Language('und'))
+                    else:
+                        embedded_subtitle_languages.add(Language('und'))
+                logger.debug('Found embedded subtitle %r', embedded_subtitle_languages)
+                video.subtitle_languages |= embedded_subtitle_languages
+        else:
+            logger.debug('MKV has no subtitle track')
+    else:
+        logger.debug('Unsupported video extension %s', extension)

subliminal/refiners/omdb.py

@@ -0,0 +1,187 @@
+# -*- coding: utf-8 -*-
+import logging
+import operator
+
+import requests
+
+from .. import __short_version__
+from ..cache import REFINER_EXPIRATION_TIME, region
+from ..video import Episode, Movie
+from ..utils import sanitize
+
+logger = logging.getLogger(__name__)
+
+
+class OMDBClient(object):
+    base_url = 'http://www.omdbapi.com'
+
+    def __init__(self, version=1, session=None, headers=None, timeout=10):
+        #: Session for the requests
+        self.session = session or requests.Session()
+        self.session.timeout = timeout
+        self.session.headers.update(headers or {})
+        self.session.params['r'] = 'json'
+        self.session.params['v'] = version
+
+    def get(self, id=None, title=None, type=None, year=None, plot='short', tomatoes=False):
+        # build the params
+        params = {}
+        if id:
+            params['i'] = id
+        if title:
+            params['t'] = title
+        if not params:
+            raise ValueError('At least id or title is required')
+        params['type'] = type
+        params['y'] = year
+        params['plot'] = plot
+        params['tomatoes'] = tomatoes
+
+        # perform the request
+        r = self.session.get(self.base_url, params=params)
+        r.raise_for_status()
+
+        # get the response as json
+        j = r.json()
+
+        # check response status
+        if j['Response'] == 'False':
+            return None
+
+        return j
+
+    def search(self, title, type=None, year=None, page=1):
+        # build the params
+        params = {'s': title, 'type': type, 'y': year, 'page': page}
+
+        # perform the request
+        r = self.session.get(self.base_url, params=params)
+        r.raise_for_status()
+
+        # get the response as json
+        j = r.json()
+
+        # check response status
+        if j['Response'] == 'False':
+            return None
+
+        return j
+
+
+omdb_client = OMDBClient(headers={'User-Agent': 'Subliminal/%s' % __short_version__})
+
+
+@region.cache_on_arguments(expiration_time=REFINER_EXPIRATION_TIME)
+def search(title, type, year):
+    results = omdb_client.search(title, type, year)
+    if not results:
+        return None
+
+    # fetch all paginated results
+    all_results = results['Search']
+    total_results = int(results['totalResults'])
+    page = 1
+    while total_results > page * 10:
+        page += 1
+        results = omdb_client.search(title, type, year, page=page)
+        all_results.extend(results['Search'])
+
+    return all_results
+
+
+def refine(video, **kwargs):
+    """Refine a video by searching `OMDb API <http://omdbapi.com/>`_.
+
+    Several :class:`~subliminal.video.Episode` attributes can be found:
+
+      * :attr:`~subliminal.video.Episode.series`
+      * :attr:`~subliminal.video.Episode.year`
+      * :attr:`~subliminal.video.Episode.series_imdb_id`
+
+    Similarly, for a :class:`~subliminal.video.Movie`:
+
+      * :attr:`~subliminal.video.Movie.title`
+      * :attr:`~subliminal.video.Movie.year`
+      * :attr:`~subliminal.video.Video.imdb_id`
+
+    """
+    if isinstance(video, Episode):
+        # exit if the information is complete
+        if video.series_imdb_id:
+            logger.debug('No need to search')
+            return
+
+        # search the series
+        results = search(video.series, 'series', video.year)
+        if not results:
+            logger.warning('No results for series')
+            return
+        logger.debug('Found %d results', len(results))
+
+        # filter the results
+        results = [r for r in results if sanitize(r['Title']) == sanitize(video.series)]
+        if not results:
+            logger.warning('No matching series found')
+            return
+
+        # process the results
+        found = False
+        for result in sorted(results, key=operator.itemgetter('Year')):
+            if video.original_series and video.year is None:
+                logger.debug('Found result for original series without year')
+                found = True
+                break
+            if video.year == int(result['Year'].split(u'\u2013')[0]):
+                logger.debug('Found result with matching year')
+                found = True
+                break
+
+        if not found:
+            logger.warning('No matching series found')
+            return
+
+        # add series information
+        logger.debug('Found series %r', result)
+        video.series = result['Title']
+        video.year = int(result['Year'].split(u'\u2013')[0])
+        video.series_imdb_id = result['imdbID']
+
+    elif isinstance(video, Movie):
+        # exit if the information is complete
+        if video.imdb_id:
+            return
+
+        # search the movie
+        results = search(video.title, 'movie', video.year)
+        if not results:
+            logger.warning('No results')
+            return
+        logger.debug('Found %d results', len(results))
+
+        # filter the results
+        results = [r for r in results if sanitize(r['Title']) == sanitize(video.title)]
+        if not results:
+            logger.warning('No matching movie found')
+            return
+
+        # process the results
+        found = False
+        for result in results:
+            if video.year is None:
+                logger.debug('Found result for movie without year')
+                found = True
+                break
+            if video.year == int(result['Year']):
+                logger.debug('Found result with matching year')
+                found = True
+                break
+
+        if not found:
+            logger.warning('No matching movie found')
+            return
+
+        # add movie information
+        logger.debug('Found movie %r', result)
+        video.title = result['Title']
+        video.year = int(result['Year'].split(u'\u2013')[0])
+        video.imdb_id = result['imdbID']

subliminal/refiners/tvdb.py

@@ -0,0 +1,350 @@
+# -*- coding: utf-8 -*-
+from datetime import datetime, timedelta
+from functools import wraps
+import logging
+import re
+
+import requests
+
+from .. import __short_version__
+from ..cache import REFINER_EXPIRATION_TIME, region
+from ..utils import sanitize
+from ..video import Episode
+
+logger = logging.getLogger(__name__)
+
+series_re = re.compile(r'^(?P<series>.*?)(?: \((?:(?P<year>\d{4})|(?P<country>[A-Z]{2}))\))?$')
+
+
+def requires_auth(func):
+    """Decorator for :class:`TVDBClient` methods that require authentication"""
+    @wraps(func)
+    def wrapper(self, *args, **kwargs):
+        if self.token is None or self.token_expired:
+            self.login()
+        elif self.token_needs_refresh:
+            self.refresh_token()
+        return func(self, *args, **kwargs)
+    return wrapper
+
+
+class TVDBClient(object):
+    """TVDB REST API Client
+
+    :param str apikey: API key to use.
+    :param str username: username to use.
+    :param str password: password to use.
+    :param str language: language of the responses.
+    :param session: session object to use.
+    :type session: :class:`requests.sessions.Session` or compatible.
+    :param dict headers: additional headers.
+    :param int timeout: timeout for the requests.
+
+    """
+    #: Base URL of the API
+    base_url = 'https://api.thetvdb.com'
+
+    #: Token lifespan
+    token_lifespan = timedelta(hours=1)
+
+    #: Minimum token age before a :meth:`refresh_token` is triggered
+    refresh_token_every = timedelta(minutes=30)
+
+    def __init__(self, apikey=None, username=None, password=None, language='en', session=None, headers=None,
+                 timeout=10):
+        #: API key
+        self.apikey = apikey
+
+        #: Username
+        self.username = username
+
+        #: Password
+        self.password = password
+
+        #: Last token acquisition date
+        self.token_date = datetime.utcnow() - self.token_lifespan
+
+        #: Session for the requests
+        self.session = session or requests.Session()
+        self.session.timeout = timeout
+        self.session.headers.update(headers or {})
+        self.session.headers['Content-Type'] = 'application/json'
+        self.session.headers['Accept-Language'] = language
+
+    @property
+    def language(self):
+        return self.session.headers['Accept-Language']
+
+    @language.setter
+    def language(self, value):
+        self.session.headers['Accept-Language'] = value
+
+    @property
+    def token(self):
+        if 'Authorization' not in self.session.headers:
+            return None
+        return self.session.headers['Authorization'][7:]
+
+    @property
+    def token_expired(self):
+        return datetime.utcnow() - self.token_date > self.token_lifespan
+
+    @property
+    def token_needs_refresh(self):
+        return datetime.utcnow() - self.token_date > self.refresh_token_every
+
+    def login(self):
+        """Login"""
+        # perform the request
+        data = {'apikey': self.apikey, 'username': self.username, 'password': self.password}
+        r = self.session.post(self.base_url + '/login', json=data)
+        r.raise_for_status()
+
+        # set the Authorization header
+        self.session.headers['Authorization'] = 'Bearer ' + r.json()['token']
+
+        # update token_date
+        self.token_date = datetime.utcnow()
+
+    def refresh_token(self):
+        """Refresh token"""
+        # perform the request
+        r = self.session.get(self.base_url + '/refresh_token')
+        r.raise_for_status()
+
+        # set the Authorization header
+        self.session.headers['Authorization'] = 'Bearer ' + r.json()['token']
+
+        # update token_date
+        self.token_date = datetime.utcnow()
+
+    @requires_auth
+    def search_series(self, name=None, imdb_id=None, zap2it_id=None):
+        """Search series"""
+        # perform the request
+        params = {'name': name, 'imdbId': imdb_id, 'zap2itId': zap2it_id}
+        r = self.session.get(self.base_url + '/search/series', params=params)
+        if r.status_code == 404:
+            return None
+        r.raise_for_status()
+
+        return r.json()['data']
+
+    @requires_auth
+    def get_series(self, id):
+        """Get series"""
+        # perform the request
+        r = self.session.get(self.base_url + '/series/{}'.format(id))
+        if r.status_code == 404:
+            return None
+        r.raise_for_status()
+
+        return r.json()['data']
+
+    @requires_auth
+    def get_series_actors(self, id):
+        """Get series actors"""
+        # perform the request
+        r = self.session.get(self.base_url + '/series/{}/actors'.format(id))
+        if r.status_code == 404:
+            return None
+        r.raise_for_status()
+
+        return r.json()['data']
+
+    @requires_auth
+    def get_series_episodes(self, id, page=1):
+        """Get series episodes"""
+        # perform the request
+        params = {'page': page}
+        r = self.session.get(self.base_url + '/series/{}/episodes'.format(id), params=params)
+        if r.status_code == 404:
+            return None
+        r.raise_for_status()
+
+        return r.json()
+
+    @requires_auth
+    def query_series_episodes(self, id, absolute_number=None, aired_season=None, aired_episode=None, dvd_season=None,
+                              dvd_episode=None, imdb_id=None, page=1):
+        """Query series episodes"""
+        # perform the request
+        params = {'absoluteNumber': absolute_number, 'airedSeason': aired_season, 'airedEpisode': aired_episode,
+                  'dvdSeason': dvd_season, 'dvdEpisode': dvd_episode, 'imdbId': imdb_id, 'page': page}
+        r = self.session.get(self.base_url + '/series/{}/episodes/query'.format(id), params=params)
+        if r.status_code == 404:
+            return None
+        r.raise_for_status()
+
+        return r.json()
+
+    @requires_auth
+    def get_episode(self, id):
+        """Get episode"""
+        # perform the request
+        r = self.session.get(self.base_url + '/episodes/{}'.format(id))
+        if r.status_code == 404:
+            return None
+        r.raise_for_status()
+
+        return r.json()['data']
+
+
+#: Configured instance of :class:`TVDBClient`
+tvdb_client = TVDBClient('5EC930FB90DA1ADA', headers={'User-Agent': 'Subliminal/%s' % __short_version__})
+
+
+@region.cache_on_arguments(expiration_time=REFINER_EXPIRATION_TIME)
+def search_series(name):
+    """Search series.
+
+    :param str name: name of the series.
+    :return: the search results.
+    :rtype: list
+
+    """
+    return tvdb_client.search_series(name)
+
+
+@region.cache_on_arguments(expiration_time=REFINER_EXPIRATION_TIME)
+def get_series(id):
+    """Get series.
+
+    :param int id: id of the series.
+    :return: the series data.
+    :rtype: dict
+
+    """
+    return tvdb_client.get_series(id)
+
+
+@region.cache_on_arguments(expiration_time=REFINER_EXPIRATION_TIME)
+def get_series_episode(series_id, season, episode):
+    """Get an episode of a series.
+
+    :param int series_id: id of the series.
+    :param int season: season number of the episode.
+    :param int episode: episode number of the episode.
+    :return: the episode data.
+    :rtype: dict
+
+    """
+    result = tvdb_client.query_series_episodes(series_id, aired_season=season, aired_episode=episode)
+    if result:
+        return tvdb_client.get_episode(result['data'][0]['id'])
+
+
+def refine(video, **kwargs):
+    """Refine a video by searching `TheTVDB <http://thetvdb.com/>`_.
+
+    .. note::
+
+        This refiner only work for instances of :class:`~subliminal.video.Episode`.
+
+    Several attributes can be found:
+
+      * :attr:`~subliminal.video.Episode.series`
+      * :attr:`~subliminal.video.Episode.year`
+      * :attr:`~subliminal.video.Episode.series_imdb_id`
+      * :attr:`~subliminal.video.Episode.series_tvdb_id`
+      * :attr:`~subliminal.video.Episode.title`
+      * :attr:`~subliminal.video.Video.imdb_id`
+      * :attr:`~subliminal.video.Episode.tvdb_id`
+
+    """
+    # only deal with Episode videos
+    if not isinstance(video, Episode):
+        logger.error('Cannot refine episodes')
+        return
+
+    # exit if the information is complete
+    if video.series_tvdb_id and video.tvdb_id:
+        logger.debug('No need to search')
+        return
+
+    # search the series
+    logger.info('Searching series %r', video.series)
+    results = search_series(video.series.lower())
+    if not results:
+        logger.warning('No results for series')
+        return
+    logger.debug('Found %d results', len(results))
+
+    # search for exact matches
+    matching_results = []
+    for result in results:
+        matching_result = {}
+
+        # use seriesName and aliases
+        series_names = [result['seriesName']]
+        series_names.extend(result['aliases'])
+
+        # parse the original series as series + year or country
+        original_match = series_re.match(result['seriesName']).groupdict()
+
+        # parse series year
+        series_year = None
+        if result['firstAired']:
+            series_year = datetime.strptime(result['firstAired'], '%Y-%m-%d').year
+
+        # discard mismatches on year
+        if video.year and series_year and video.year != series_year:
+            logger.debug('Discarding series %r mismatch on year %d', result['seriesName'], series_year)
+            continue
+
+        # iterate over series names
+        for series_name in series_names:
+            # parse as series and year
+            series, year, country = series_re.match(series_name).groups()
+            if year:
+                year = int(year)
+
+            # discard mismatches on year
+            if year and (video.original_series or video.year != year):
+                logger.debug('Discarding series name %r mismatch on year %d', series, year)
+                continue
+
+            # match on sanitized series name
+            if sanitize(series) == sanitize(video.series):
+                logger.debug('Found exact match on series %r', series_name)
+                matching_result['match'] = {'series': original_match['series'], 'year': series_year,
+                                            'original_series': original_match['year'] is None}
+                break
+
+        # add the result on match
+        if matching_result:
+            matching_result['data'] = result
+            matching_results.append(matching_result)
+
+    # exit if we don't have exactly 1 matching result
+    if not matching_results:
+        logger.error('No matching series found')
+        return
+    if len(matching_results) > 1:
+        logger.error('Multiple matches found')
+        return
+
+    # get the series
+    matching_result = matching_results[0]
+    series = get_series(matching_result['data']['id'])
+
+    # add series information
+    logger.debug('Found series %r', series)
+    video.series = matching_result['match']['series']
+    video.year = matching_result['match']['year']
+    video.original_series = matching_result['match']['original_series']
+    video.series_tvdb_id = series['id']
+    video.series_imdb_id = series['imdbId'] or None
+
+    # get the episode
+    logger.info('Getting series episode %dx%d', video.season, video.episode)
+    episode = get_series_episode(video.series_tvdb_id, video.season, video.episode)
+    if not episode:
+        logger.warning('No results for episode')
+        return
+
+    # add episode information
+    logger.debug('Found episode %r', episode)
+    video.tvdb_id = episode['id']
+    video.title = episode['episodeName'] or None
+    video.imdb_id = episode['imdbId'] or None

subliminal/score.py

@@ -0,0 +1,213 @@
+# -*- coding: utf-8 -*-
+"""
+This module provides the default implementation of the `compute_score` parameter in
+:meth:`~subliminal.core.ProviderPool.download_best_subtitles` and :func:`~subliminal.core.download_best_subtitles`.
+
+.. note::
+
+    To avoid unnecessary dependency on `sympy <http://www.sympy.org/>`_ and boost subliminal's import time, the
+    resulting scores are hardcoded here and manually updated when the set of equations change.
+
+Available matches:
+
+  * hash
+  * title
+  * year
+  * series
+  * season
+  * episode
+  * release_group
+  * format
+  * audio_codec
+  * resolution
+  * hearing_impaired
+  * video_codec
+  * series_imdb_id
+  * imdb_id
+  * tvdb_id
+
+"""
+from __future__ import division, print_function
+import logging
+
+from .video import Episode, Movie
+
+logger = logging.getLogger(__name__)
+
+
+#: Scores for episodes
+episode_scores = {'hash': 359, 'series': 180, 'year': 90, 'season': 30, 'episode': 30, 'release_group': 15,
+                  'format': 7, 'audio_codec': 3, 'resolution': 2, 'video_codec': 2, 'hearing_impaired': 1}
+
+#: Scores for movies
+movie_scores = {'hash': 119, 'title': 60, 'year': 30, 'release_group': 15,
+                'format': 7, 'audio_codec': 3, 'resolution': 2, 'video_codec': 2, 'hearing_impaired': 1}
+
+
+def get_scores(video):
+    """Get the scores dict for the given `video`.
+
+    This will return either :data:`episode_scores` or :data:`movie_scores` based on the type of the `video`.
+
+    :param video: the video to compute the score against.
+    :type video: :class:`~subliminal.video.Video`
+    :return: the scores dict.
+    :rtype: dict
+
+    """
+    if isinstance(video, Episode):
+        return episode_scores
+    elif isinstance(video, Movie):
+        return movie_scores
+
+    raise ValueError('video must be an instance of Episode or Movie')
+
+
+def compute_score(subtitle, video, hearing_impaired=None):
+    """Compute the score of the `subtitle` against the `video` with `hearing_impaired` preference.
+
+    :func:`compute_score` uses the :meth:`Subtitle.get_matches <subliminal.subtitle.Subtitle.get_matches>` method and
+    applies the scores (either from :data:`episode_scores` or :data:`movie_scores`) after some processing.
+
+    :param subtitle: the subtitle to compute the score of.
+    :type subtitle: :class:`~subliminal.subtitle.Subtitle`
+    :param video: the video to compute the score against.
+    :type video: :class:`~subliminal.video.Video`
+    :param bool hearing_impaired: hearing impaired preference.
+    :return: score of the subtitle.
+    :rtype: int
+
+    """
+    logger.info('Computing score of %r for video %r with %r', subtitle, video, dict(hearing_impaired=hearing_impaired))
+
+    # get the scores dict
+    scores = get_scores(video)
+    logger.debug('Using scores %r', scores)
+
+    # get the matches
+    matches = subtitle.get_matches(video)
+    logger.debug('Found matches %r', matches)
+
+    # on hash match, discard everything else
+    if 'hash' in matches:
+        logger.debug('Keeping only hash match')
+        matches &= {'hash'}
+
+    # handle equivalent matches
+    if isinstance(video, Episode):
+        if 'title' in matches:
+            logger.debug('Adding title match equivalent')
+            matches.add('episode')
+        if 'series_imdb_id' in matches:
+            logger.debug('Adding series_imdb_id match equivalent')
+            matches |= {'series', 'year'}
+        if 'imdb_id' in matches:
+            logger.debug('Adding imdb_id match equivalents')
+            matches |= {'series', 'year', 'season', 'episode'}
+        if 'tvdb_id' in matches:
+            logger.debug('Adding tvdb_id match equivalents')
+            matches |= {'series', 'year'}
+    elif isinstance(video, Movie):
+        if 'imdb_id' in matches:
+            logger.debug('Adding imdb_id match equivalents')
+            matches |= {'title', 'year'}
+
+    # handle hearing impaired
+    if hearing_impaired is not None and subtitle.hearing_impaired == hearing_impaired:
+        logger.debug('Matched hearing_impaired')
+        matches.add('hearing_impaired')
+
+    # compute the score
+    score = sum((scores.get(match, 0) for match in matches))
+    logger.info('Computed score %r with final matches %r', score, matches)
+
+    # ensure score is within valid bounds
+    assert 0 <= score <= scores['hash'] + scores['hearing_impaired']
+
+    return score
+
+
+def solve_episode_equations():
+    from sympy import Eq, solve, symbols
+
+    hash, series, year, season, episode, release_group = symbols('hash series year season episode release_group')
+    format, audio_codec, resolution, video_codec = symbols('format audio_codec resolution video_codec')
+    hearing_impaired = symbols('hearing_impaired')
+
+    equations = [
+        # hash is best
+        Eq(hash, series + year + season + episode + release_group + format + audio_codec + resolution + video_codec),
+
+        # series counts for the most part in the total score
+        Eq(series, year + season + episode + release_group + format + audio_codec + resolution + video_codec + 1),
+
+        # year is the second most important part
+        Eq(year, season + episode + release_group + format + audio_codec + resolution + video_codec + 1),
+
+        # season is important too
+        Eq(season, release_group + format + audio_codec + resolution + video_codec + 1),
+
+        # episode is equally important to season
+        Eq(episode, season),
+
+        # release group is the next most wanted match
+        Eq(release_group, format + audio_codec + resolution + video_codec + 1),
+
+        # format counts as much as audio_codec, resolution and video_codec
+        Eq(format, audio_codec + resolution + video_codec),
+
+        # audio_codec is more valuable than video_codec
+        Eq(audio_codec, video_codec + 1),
+
+        # resolution counts as much as video_codec
+        Eq(resolution, video_codec),
+
+        # video_codec is the least valuable match but counts more than the sum of all scoring increasing matches
+        Eq(video_codec, hearing_impaired + 1),
+
+        # hearing impaired is only used for score increasing, so put it to 1
+        Eq(hearing_impaired, 1),
+    ]
+
+    return solve(equations, [hash, series, year, season, episode, release_group, format, audio_codec, resolution,
+                             hearing_impaired, video_codec])
+
+
+def solve_movie_equations():
+    from sympy import Eq, solve, symbols
+
+    hash, title, year, release_group = symbols('hash title year release_group')
+    format, audio_codec, resolution, video_codec = symbols('format audio_codec resolution video_codec')
+    hearing_impaired = symbols('hearing_impaired')
+
+    equations = [
+        # hash is best
+        Eq(hash, title + year + release_group + format + audio_codec + resolution + video_codec),
+
+        # title counts for the most part in the total score
+        Eq(title, year + release_group + format + audio_codec + resolution + video_codec + 1),
+
+        # year is the second most important part
+        Eq(year, release_group + format + audio_codec + resolution + video_codec + 1),
+
+        # release group is the next most wanted match
+        Eq(release_group, format + audio_codec + resolution + video_codec + 1),
+
+        # format counts as much as audio_codec, resolution and video_codec
+        Eq(format, audio_codec + resolution + video_codec),
+
+        # audio_codec is more valuable than video_codec
+        Eq(audio_codec, video_codec + 1),
+
+        # resolution counts as much as video_codec
+        Eq(resolution, video_codec),
+
+        # video_codec is the least valuable match but counts more than the sum of all scoring increasing matches
+        Eq(video_codec, hearing_impaired + 1),
+
+        # hearing impaired is only used for score increasing, so put it to 1
+        Eq(hearing_impaired, 1),
+    ]
+
+    return solve(equations, [hash, title, year, release_group, format, audio_codec, resolution, hearing_impaired,
+                             video_codec])

subliminal/services/__init__.py

@@ -1,256 +0,0 @@
-# -*- coding: utf-8 -*-
-# Copyright 2011-2012 Antoine Bertin <diaoulael@gmail.com>
-#
-# This file is part of subliminal.
-#
-# subliminal is free software; you can redistribute it and/or modify it under
-# the terms of the GNU Lesser General Public License as published by
-# the Free Software Foundation; either version 3 of the License, or
-# (at your option) any later version.
-#
-# subliminal is distributed in the hope that it will be useful,
-# but WITHOUT ANY WARRANTY; without even the implied warranty of
-# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
-# GNU Lesser General Public License for more details.
-#
-# You should have received a copy of the GNU Lesser General Public License
-# along with subliminal.  If not, see <http://www.gnu.org/licenses/>.
-from ..cache import Cache
-from ..exceptions import DownloadFailedError, ServiceError
-from ..language import language_set, Language
-from ..subtitles import EXTENSIONS
-import logging
-import os
-import requests
-import threading
-import zipfile
-
-
-__all__ = ['ServiceBase', 'ServiceConfig']
-logger = logging.getLogger(__name__)
-
-
-class ServiceBase(object):
-    """Service base class
-
-    :param config: service configuration
-    :type config: :class:`ServiceConfig`
-
-    """
-    #: URL to the service server
-    server_url = ''
-
-    #: User Agent for any HTTP-based requests
-    user_agent = 'subliminal v0.6'
-
-    #: Whether based on an API or not
-    api_based = False
-
-    #: Timeout for web requests
-    timeout = 5
-
-    #: :class:`~subliminal.language.language_set` of available languages
-    languages = language_set()
-
-    #: Map between language objects and language codes used in the service
-    language_map = {}
-
-    #: Default attribute of a :class:`~subliminal.language.Language` to get with :meth:`get_code`
-    language_code = 'alpha2'
-
-    #: Accepted video classes (:class:`~subliminal.videos.Episode`, :class:`~subliminal.videos.Movie`, :class:`~subliminal.videos.UnknownVideo`)
-    videos = []
-
-    #: Whether the video has to exist or not
-    require_video = False
-
-    #: List of required features for BeautifulSoup
-    required_features = None
-
-    def __init__(self, config=None):
-        self.config = config or ServiceConfig()
-        self.session = None
-
-    def __enter__(self):
-        self.init()
-        return self
-
-    def __exit__(self, *args):
-        self.terminate()
-
-    def init(self):
-        """Initialize connection"""
-        logger.debug(u'Initializing %s' % self.__class__.__name__)
-        self.session = requests.session(timeout=10, headers={'User-Agent': self.user_agent})
-
-    def init_cache(self):
-        """Initialize cache, make sure it is loaded from disk"""
-        if not self.config or not self.config.cache:
-            raise ServiceError('Cache directory is required')
-        self.config.cache.load(self.__class__.__name__)
-
-    def save_cache(self):
-        self.config.cache.save(self.__class__.__name__)
-
-    def clear_cache(self):
-        self.config.cache.clear(self.__class__.__name__)
-
-    def cache_for(self, func, args, result):
-        return self.config.cache.cache_for(self.__class__.__name__, func, args, result)
-
-    def cached_value(self, func, args):
-        return self.config.cache.cached_value(self.__class__.__name__, func, args)
-
-    def terminate(self):
-        """Terminate connection"""
-        logger.debug(u'Terminating %s' % self.__class__.__name__)
-
-    def get_code(self, language):
-        """Get the service code for a :class:`~subliminal.language.Language`
-
-        It uses the :data:`language_map` and if there's no match, falls back
-        on the :data:`language_code` attribute of the given :class:`~subliminal.language.Language`
-
-        """
-        if language in self.language_map:
-            return self.language_map[language]
-        if self.language_code is None:
-            raise ValueError('%r has no matching code' % language)
-        return getattr(language, self.language_code)
-
-    def get_language(self, code):
-        """Get a :class:`~subliminal.language.Language` from a service code
-
-        It uses the :data:`language_map` and if there's no match, uses the
-        given code as ``language`` parameter for the :class:`~subliminal.language.Language`
-        constructor
-
-        .. note::
-
-            A warning is emitted if the generated :class:`~subliminal.language.Language`
-            is "Undetermined"
-
-        """
-        if code in self.language_map:
-            return self.language_map[code]
-        language = Language(code, strict=False)
-        if language == Language('Undetermined'):
-            logger.warning(u'Code %s could not be identified as a language for %s' % (code, self.__class__.__name__))
-        return language
-
-    def query(self, *args):
-        """Make the actual query"""
-        raise NotImplementedError()
-
-    def list(self, video, languages):
-        """List subtitles
-
-        As a service writer, you can either override this method or implement
-        :meth:`list_checked` instead to have the languages pre-filtered for you
-
-        """
-        if not self.check_validity(video, languages):
-            return []
-        return self.list_checked(video, languages)
-
-    def list_checked(self, video, languages):
-        """List subtitles without having to check parameters for validity"""
-        raise NotImplementedError()
-
-    def download(self, subtitle):
-        """Download a subtitle"""
-        self.download_file(subtitle.link, subtitle.path)
-        return subtitle
-
-    @classmethod
-    def check_validity(cls, video, languages):
-        """Check for video and languages validity in the Service
-
-        :param video: the video to check
-        :type video: :class:`~subliminal.videos.video`
-        :param languages: languages to check
-        :type languages: :class:`~subliminal.language.Language`
-        :rtype: bool
-
-        """
-        languages = (languages & cls.languages) - language_set(['Undetermined'])
-        if not languages:
-            logger.debug(u'No language available for service %s' % cls.__name__.lower())
-            return False
-        if cls.require_video and not video.exists or not isinstance(video, tuple(cls.videos)):
-            logger.debug(u'%r is not valid for service %s' % (video, cls.__name__.lower()))
-            return False
-        return True
-
-    def download_file(self, url, filepath):
-        """Attempt to download a file and remove it in case of failure
-
-        :param string url: URL to download
-        :param string filepath: destination path
-
-        """
-        logger.info(u'Downloading %s in %s' % (url, filepath))
-        try:
-            r = self.session.get(url, headers={'Referer': url, 'User-Agent': self.user_agent})
-            with open(filepath, 'wb') as f:
-                f.write(r.content)
-        except Exception as e:
-            logger.error(u'Download failed: %s' % e)
-            if os.path.exists(filepath):
-                os.remove(filepath)
-            raise DownloadFailedError(str(e))
-        logger.debug(u'Download finished')
-
-    def download_zip_file(self, url, filepath):
-        """Attempt to download a zip file and extract any subtitle file from it, if any.
-        This cleans up after itself if anything fails.
-
-        :param string url: URL of the zip file to download
-        :param string filepath: destination path for the subtitle
-
-        """
-        logger.info(u'Downloading %s in %s' % (url, filepath))
-        try:
-            zippath = filepath + '.zip'
-            r = self.session.get(url, headers={'Referer': url, 'User-Agent': self.user_agent})
-            with open(zippath, 'wb') as f:
-                f.write(r.content)
-            if not zipfile.is_zipfile(zippath):
-                # TODO: could check if maybe we already have a text file and
-                # download it directly
-                raise DownloadFailedError('Downloaded file is not a zip file')
-            with zipfile.ZipFile(zippath) as zipsub:
-                for subfile in zipsub.namelist():
-                    if os.path.splitext(subfile)[1] in EXTENSIONS:
-                        with open(filepath, 'w') as f:
-                            f.write(zipsub.open(subfile).read())
-                        break
-                else:
-                    raise DownloadFailedError('No subtitles found in zip file')
-            os.remove(zippath)
-        except Exception as e:
-            logger.error(u'Download %s failed: %s' % (url, e))
-            if os.path.exists(zippath):
-                os.remove(zippath)
-            if os.path.exists(filepath):
-                os.remove(filepath)
-            raise DownloadFailedError(str(e))
-        logger.debug(u'Download finished')
-
-
-class ServiceConfig(object):
-    """Configuration for any :class:`Service`
-
-    :param bool multi: whether to download one subtitle per language or not
-    :param string cache_dir: cache directory
-
-    """
-    def __init__(self, multi=False, cache_dir=None):
-        self.multi = multi
-        self.cache_dir = cache_dir
-        self.cache = None
-        if cache_dir is not None:
-            self.cache = Cache(cache_dir)
-
-    def __repr__(self):
-        return 'ServiceConfig(%r, %s)' % (self.multi, self.cache.cache_dir)

subliminal/services/addic7ed.py

@@ -1,173 +0,0 @@
-# -*- coding: utf-8 -*-
-# Copyright 2012 Olivier Leveau <olifozzy@gmail.com>
-#
-# This file is part of subliminal.
-#
-# subliminal is free software; you can redistribute it and/or modify it under
-# the terms of the GNU Lesser General Public License as published by
-# the Free Software Foundation; either version 3 of the License, or
-# (at your option) any later version.
-#
-# subliminal is distributed in the hope that it will be useful,
-# but WITHOUT ANY WARRANTY; without even the implied warranty of
-# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
-# GNU Lesser General Public License for more details.
-#
-# You should have received a copy of the GNU Lesser General Public License
-# along with subliminal.  If not, see <http://www.gnu.org/licenses/>.
-from . import ServiceBase
-from ..cache import cachedmethod
-from ..exceptions import DownloadFailedError
-from ..language import Language, language_set
-from ..subtitles import get_subtitle_path, ResultSubtitle
-from ..utils import get_keywords
-from ..videos import Episode
-from bs4 import BeautifulSoup
-import logging
-import os
-import re
-
-
-logger = logging.getLogger(__name__)
-
-
-def match(pattern, string):
-    try:
-        return re.search(pattern, string).group(1)
-    except AttributeError:
-        logger.debug(u'Could not match %r on %r' % (pattern, string))
-        return None
-
-
-def matches(pattern, string):
-    try:
-        return re.search(pattern, string).group(1, 2)
-    except AttributeError:
-        logger.debug(u'Could not match %r on %r' % (pattern, string))
-        return None
-
-
-class Addic7ed(ServiceBase):
-    server_url = 'http://www.addic7ed.com'
-    api_based = False
-    #TODO: Complete this
-    languages = language_set(['ar', 'ca', 'de', 'el', 'en', 'es', 'eu', 'fr', 'ga', 'he', 'hr', 'hu', 'it',
-                              'pl', 'pt', 'ro', 'ru', 'se', 'pt-br'])
-    language_map = {'Portuguese (Brazilian)': Language('por-BR'), 'Greek': Language('gre'),
-                    'Spanish (Latin America)': Language('spa'), }
-    videos = [Episode]
-    require_video = False
-    required_features = ['permissive']
-
-    @cachedmethod
-    def get_likely_series_id(self, name):
-        r = self.session.get('%s/shows.php' % self.server_url)
-        soup = BeautifulSoup(r.content, self.required_features)
-        for elem in soup.find_all('h3'):
-            show_name = elem.a.text.lower()
-            show_id = int(match('show/([0-9]+)', elem.a['href']))
-            # we could just return the id of the queried show, but as we
-            # already downloaded the whole page we might as well fill in the
-            # information for all the shows
-            self.cache_for(self.get_likely_series_id, args=(show_name,), result=show_id)
-        return self.cached_value(self.get_likely_series_id, args=(name,))
-
-    @cachedmethod
-    def get_episode_url(self, series_id, season, number):
-        """Get the Addic7ed id for the given episode. Raises KeyError if none
-        could be found
-
-        """
-        # download the page of the show, contains ids for all episodes all seasons
-        r = self.session.get('%s/show/%d' % (self.server_url, series_id))
-        soup = BeautifulSoup(r.content, self.required_features)
-        form = soup.find('form', attrs={'name': 'multidl'})
-        for table in form.find_all('table'):
-            for row in table.find_all('tr'):
-                cell = row.find('td', 'MultiDldS')
-                if not cell:
-                    continue
-                m = matches('/serie/.+/([0-9]+)/([0-9]+)/', cell.a['href'])
-                if not m:
-                    continue
-                episode_url = cell.a['href']
-                season_number = int(m[0])
-                episode_number = int(m[1])
-                # we could just return the url of the queried episode, but as we
-                # already downloaded the whole page we might as well fill in the
-                # information for all the episodes of the show
-                self.cache_for(self.get_episode_url, args=(series_id, season_number, episode_number), result=episode_url)
-        # raises KeyError if not found
-        return self.cached_value(self.get_episode_url, args=(series_id, season, number))
-
-    # Do not cache this method in order to always check for the most recent
-    # subtitles
-    def get_sub_urls(self, episode_url):
-        suburls = []
-        r = self.session.get('%s/%s' % (self.server_url, episode_url))
-        epsoup = BeautifulSoup(r.content, self.required_features)
-        for releaseTable in epsoup.find_all('table', 'tabel95'):
-            releaseRow = releaseTable.find('td', 'NewsTitle')
-            if not releaseRow:
-                continue
-            release = releaseRow.text.strip()
-            for row in releaseTable.find_all('tr'):
-                link = row.find('a', 'buttonDownload')
-                if not link:
-                    continue
-                if 'href' not in link.attrs or not (link['href'].startswith('/original') or link['href'].startswith('/updated')):
-                    continue
-                suburl = link['href']
-                lang = self.get_language(row.find('td', 'language').text.strip())
-                result = {'suburl': suburl, 'language': lang, 'release': release}
-                suburls.append(result)
-        return suburls
-
-    def list_checked(self, video, languages):
-        return self.query(video.path or video.release, languages, get_keywords(video.guess), video.series, video.season, video.episode)
-
-    def query(self, filepath, languages, keywords, series, season, episode):
-        logger.debug(u'Getting subtitles for %s season %d episode %d with languages %r' % (series, season, episode, languages))
-        self.init_cache()
-        try:
-            sid = self.get_likely_series_id(series.lower())
-        except KeyError:
-            logger.debug(u'Could not find series id for %s' % series)
-            return []
-        try:
-            ep_url = self.get_episode_url(sid, season, episode)
-        except KeyError:
-            logger.debug(u'Could not find episode id for %s season %d episode %d' % (series, season, episode))
-            return []
-        suburls = self.get_sub_urls(ep_url)
-        # filter the subtitles with our queried languages
-        subtitles = []
-        for suburl in suburls:
-            language = suburl['language']
-            if language not in languages:
-                continue
-            path = get_subtitle_path(filepath, language, self.config.multi)
-            subtitle = ResultSubtitle(path, language, self.__class__.__name__.lower(), '%s/%s' % (self.server_url, suburl['suburl']),
-                                      keywords=[suburl['release']])
-            subtitles.append(subtitle)
-        return subtitles
-
-    def download(self, subtitle):
-        logger.info(u'Downloading %s in %s' % (subtitle.link, subtitle.path))
-        try:
-            r = self.session.get(subtitle.link, headers={'Referer': subtitle.link, 'User-Agent': self.user_agent})
-            soup = BeautifulSoup(r.content, self.required_features)
-            if soup.title is not None and u'Addic7ed.com' in soup.title.text.strip():
-                raise DownloadFailedError('Download limit exceeded')
-            with open(subtitle.path, 'wb') as f:
-                f.write(r.content)
-        except Exception as e:
-            logger.error(u'Download failed: %s' % e)
-            if os.path.exists(subtitle.path):
-                os.remove(subtitle.path)
-            raise DownloadFailedError(str(e))
-        logger.debug(u'Download finished')
-        return subtitle
-
-
-Service = Addic7ed

subliminal/services/bierdopje.py

@@ -1,102 +0,0 @@
-# -*- coding: utf-8 -*-
-# Copyright 2011-2012 Antoine Bertin <diaoulael@gmail.com>
-#
-# This file is part of subliminal.
-#
-# subliminal is free software; you can redistribute it and/or modify it under
-# the terms of the GNU Lesser General Public License as published by
-# the Free Software Foundation; either version 3 of the License, or
-# (at your option) any later version.
-#
-# subliminal is distributed in the hope that it will be useful,
-# but WITHOUT ANY WARRANTY; without even the implied warranty of
-# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
-# GNU Lesser General Public License for more details.
-#
-# You should have received a copy of the GNU Lesser General Public License
-# along with subliminal.  If not, see <http://www.gnu.org/licenses/>.
-from . import ServiceBase
-from ..cache import cachedmethod
-from ..exceptions import ServiceError
-from ..language import language_set
-from ..subtitles import get_subtitle_path, ResultSubtitle, EXTENSIONS
-from ..utils import to_unicode
-from ..videos import Episode
-from bs4 import BeautifulSoup
-import logging
-import urllib
-try:
-    import cPickle as pickle
-except ImportError:
-    import pickle
-
-
-logger = logging.getLogger(__name__)
-
-
-class BierDopje(ServiceBase):
-    server_url = 'http://api.bierdopje.com/A2B638AC5D804C2E/'
-    api_based = True
-    languages = language_set(['eng', 'dut'])
-    videos = [Episode]
-    require_video = False
-    required_features = ['xml']
-
-    @cachedmethod
-    def get_show_id(self, series):
-        r = self.session.get('%sGetShowByName/%s' % (self.server_url, urllib.quote(series.lower())))
-        if r.status_code != 200:
-            logger.error(u'Request %s returned status code %d' % (r.url, r.status_code))
-            return None
-        soup = BeautifulSoup(r.content, self.required_features)
-        if soup.status.contents[0] == 'false':
-            logger.debug(u'Could not find show %s' % series)
-            return None
-        return int(soup.showid.contents[0])
-
-    def load_cache(self):
-        logger.debug(u'Loading showids from cache...')
-        with self.lock:
-            with open(self.showids_cache, 'r') as f:
-                self.showids = pickle.load(f)
-
-    def query(self, filepath, season, episode, languages, tvdbid=None, series=None):
-        self.init_cache()
-        if series:
-            request_id = self.get_show_id(series.lower())
-            if request_id is None:
-                return []
-            request_source = 'showid'
-            request_is_tvdbid = 'false'
-        elif tvdbid:
-            request_id = tvdbid
-            request_source = 'tvdbid'
-            request_is_tvdbid = 'true'
-        else:
-            raise ServiceError('One or more parameter missing')
-        subtitles = []
-        for language in languages:
-            logger.debug(u'Getting subtitles for %s %d season %d episode %d with language %s' % (request_source, request_id, season, episode, language.alpha2))
-            r = self.session.get('%sGetAllSubsFor/%s/%s/%s/%s/%s' % (self.server_url, request_id, season, episode, language.alpha2, request_is_tvdbid))
-            if r.status_code != 200:
-                logger.error(u'Request %s returned status code %d' % (r.url, r.status_code))
-                return []
-            soup = BeautifulSoup(r.content, self.required_features)
-            if soup.status.contents[0] == 'false':
-                logger.debug(u'Could not find subtitles for %s %d season %d episode %d with language %s' % (request_source, request_id, season, episode, language.alpha2))
-                continue
-            path = get_subtitle_path(filepath, language, self.config.multi)
-            for result in soup.results('result'):
-                release = to_unicode(result.filename.contents[0])
-                if not release.endswith(tuple(EXTENSIONS)):
-                    release += '.srt'
-                subtitle = ResultSubtitle(path, language, self.__class__.__name__.lower(), result.downloadlink.contents[0],
-                                          release=release)
-                subtitles.append(subtitle)
-        return subtitles
-
-    def list_checked(self, video, languages):
-        return self.query(video.path or video.release, video.season, video.episode, languages, video.tvdbid, video.series)
-
-
-Service = BierDopje

subliminal/services/opensubtitles.py

@@ -1,158 +0,0 @@
-# -*- coding: utf-8 -*-
-# Copyright 2011-2012 Antoine Bertin <diaoulael@gmail.com>
-#
-# This file is part of subliminal.
-#
-# subliminal is free software; you can redistribute it and/or modify it under
-# the terms of the GNU Lesser General Public License as published by
-# the Free Software Foundation; either version 3 of the License, or
-# (at your option) any later version.
-#
-# subliminal is distributed in the hope that it will be useful,
-# but WITHOUT ANY WARRANTY; without even the implied warranty of
-# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
-# GNU Lesser General Public License for more details.
-#
-# You should have received a copy of the GNU Lesser General Public License
-# along with subliminal.  If not, see <http://www.gnu.org/licenses/>.
-from . import ServiceBase
-from ..exceptions import ServiceError, DownloadFailedError
-from ..language import Language, language_set
-from ..subtitles import get_subtitle_path, ResultSubtitle
-from ..utils import to_unicode
-from ..videos import Episode, Movie
-import gzip
-import logging
-import os.path
-import xmlrpclib
-
-
-logger = logging.getLogger(__name__)
-
-
-class OpenSubtitles(ServiceBase):
-    server_url = 'http://api.opensubtitles.org/xml-rpc'
-    api_based = True
-    # Source: http://www.opensubtitles.org/addons/export_languages.php
-    languages = language_set(['aar', 'abk', 'ace', 'ach', 'ada', 'ady', 'afa', 'afh', 'afr', 'ain', 'aka', 'akk',
-                              'alb', 'ale', 'alg', 'alt', 'amh', 'ang', 'apa', 'ara', 'arc', 'arg', 'arm', 'arn',
-                              'arp', 'art', 'arw', 'asm', 'ast', 'ath', 'aus', 'ava', 'ave', 'awa', 'aym', 'aze',
-                              'bad', 'bai', 'bak', 'bal', 'bam', 'ban', 'baq', 'bas', 'bat', 'bej', 'bel', 'bem',
-                              'ben', 'ber', 'bho', 'bih', 'bik', 'bin', 'bis', 'bla', 'bnt', 'bos', 'bra', 'bre',
-                              'btk', 'bua', 'bug', 'bul', 'bur', 'byn', 'cad', 'cai', 'car', 'cat', 'cau', 'ceb',
-                              'cel', 'cha', 'chb', 'che', 'chg', 'chi', 'chk', 'chm', 'chn', 'cho', 'chp', 'chr',
-                              'chu', 'chv', 'chy', 'cmc', 'cop', 'cor', 'cos', 'cpe', 'cpf', 'cpp', 'cre', 'crh',
-                              'crp', 'csb', 'cus', 'cze', 'dak', 'dan', 'dar', 'day', 'del', 'den', 'dgr', 'din',
-                              'div', 'doi', 'dra', 'dua', 'dum', 'dut', 'dyu', 'dzo', 'efi', 'egy', 'eka', 'ell',
-                              'elx', 'eng', 'enm', 'epo', 'est', 'ewe', 'ewo', 'fan', 'fao', 'fat', 'fij', 'fil',
-                              'fin', 'fiu', 'fon', 'fre', 'frm', 'fro', 'fry', 'ful', 'fur', 'gaa', 'gay', 'gba',
-                              'gem', 'geo', 'ger', 'gez', 'gil', 'gla', 'gle', 'glg', 'glv', 'gmh', 'goh', 'gon',
-                              'gor', 'got', 'grb', 'grc', 'grn', 'guj', 'gwi', 'hai', 'hat', 'hau', 'haw', 'heb',
-                              'her', 'hil', 'him', 'hin', 'hit', 'hmn', 'hmo', 'hrv', 'hun', 'hup', 'iba', 'ibo',
-                              'ice', 'ido', 'iii', 'ijo', 'iku', 'ile', 'ilo', 'ina', 'inc', 'ind', 'ine', 'inh',
-                              'ipk', 'ira', 'iro', 'ita', 'jav', 'jpn', 'jpr', 'jrb', 'kaa', 'kab', 'kac', 'kal',
-                              'kam', 'kan', 'kar', 'kas', 'kau', 'kaw', 'kaz', 'kbd', 'kha', 'khi', 'khm', 'kho',
-                              'kik', 'kin', 'kir', 'kmb', 'kok', 'kom', 'kon', 'kor', 'kos', 'kpe', 'krc', 'kro',
-                              'kru', 'kua', 'kum', 'kur', 'kut', 'lad', 'lah', 'lam', 'lao', 'lat', 'lav', 'lez',
-                              'lim', 'lin', 'lit', 'lol', 'loz', 'ltz', 'lua', 'lub', 'lug', 'lui', 'lun', 'luo',
-                              'lus', 'mac', 'mad', 'mag', 'mah', 'mai', 'mak', 'mal', 'man', 'mao', 'map', 'mar',
-                              'mas', 'may', 'mdf', 'mdr', 'men', 'mga', 'mic', 'min', 'mkh', 'mlg', 'mlt', 'mnc',
-                              'mni', 'mno', 'moh', 'mon', 'mos', 'mun', 'mus', 'mwl', 'mwr', 'myn', 'myv', 'nah',
-                              'nai', 'nap', 'nau', 'nav', 'nbl', 'nde', 'ndo', 'nds', 'nep', 'new', 'nia', 'nic',
-                              'niu', 'nno', 'nob', 'nog', 'non', 'nor', 'nso', 'nub', 'nwc', 'nya', 'nym', 'nyn',
-                              'nyo', 'nzi', 'oci', 'oji', 'ori', 'orm', 'osa', 'oss', 'ota', 'oto', 'paa', 'pag',
-                              'pal', 'pam', 'pan', 'pap', 'pau', 'peo', 'per', 'phi', 'phn', 'pli', 'pol', 'pon',
-                              'por', 'pra', 'pro', 'pus', 'que', 'raj', 'rap', 'rar', 'roa', 'roh', 'rom', 'rum',
-                              'run', 'rup', 'rus', 'sad', 'sag', 'sah', 'sai', 'sal', 'sam', 'san', 'sas', 'sat',
-                              'scn', 'sco', 'sel', 'sem', 'sga', 'sgn', 'shn', 'sid', 'sin', 'sio', 'sit', 'sla',
-                              'slo', 'slv', 'sma', 'sme', 'smi', 'smj', 'smn', 'smo', 'sms', 'sna', 'snd', 'snk',
-                              'sog', 'som', 'son', 'sot', 'spa', 'srd', 'srp', 'srr', 'ssa', 'ssw', 'suk', 'sun',
-                              'sus', 'sux', 'swa', 'swe', 'syr', 'tah', 'tai', 'tam', 'tat', 'tel', 'tem', 'ter',
-                              'tet', 'tgk', 'tgl', 'tha', 'tib', 'tig', 'tir', 'tiv', 'tkl', 'tlh', 'tli', 'tmh',
-                              'tog', 'ton', 'tpi', 'tsi', 'tsn', 'tso', 'tuk', 'tum', 'tup', 'tur', 'tut', 'tvl',
-                              'twi', 'tyv', 'udm', 'uga', 'uig', 'ukr', 'umb', 'urd', 'uzb', 'vai', 'ven', 'vie',
-                              'vol', 'vot', 'wak', 'wal', 'war', 'was', 'wel', 'wen', 'wln', 'wol', 'xal', 'xho',
-                              'yao', 'yap', 'yid', 'yor', 'ypk', 'zap', 'zen', 'zha', 'znd', 'zul', 'zun',
-                              'por-BR', 'rum-MD'])
-    language_map = {'mol': Language('rum-MD'), 'scc': Language('srp'), 'pob': Language('por-BR'),
-                    Language('rum-MD'): 'mol', Language('srp'): 'scc', Language('por-BR'): 'pob'}
-    language_code = 'alpha3'
-    videos = [Episode, Movie]
-    require_video = False
-    confidence_order = ['moviehash', 'imdbid', 'fulltext']
-
-    def __init__(self, config=None):
-        super(OpenSubtitles, self).__init__(config)
-        self.server = xmlrpclib.ServerProxy(self.server_url)
-        self.token = None
-
-    def init(self):
-        super(OpenSubtitles, self).init()
-        result = self.server.LogIn('', '', 'eng', self.user_agent)
-        if result['status'] != '200 OK':
-            raise ServiceError('Login failed')
-        self.token = result['token']
-
-    def terminate(self):
-        super(OpenSubtitles, self).terminate()
-        if self.token:
-            self.server.LogOut(self.token)
-
-    def query(self, filepath, languages, moviehash=None, size=None, imdbid=None, query=None):
-        searches = []
-        if moviehash and size:
-            searches.append({'moviehash': moviehash, 'moviebytesize': size})
-        if imdbid:
-            searches.append({'imdbid': imdbid})
-        if query:
-            searches.append({'query': query})
-        if not searches:
-            raise ServiceError('One or more parameter missing')
-        for search in searches:
-            search['sublanguageid'] = ','.join(self.get_code(l) for l in languages)
-        logger.debug(u'Getting subtitles %r with token %s' % (searches, self.token))
-        results = self.server.SearchSubtitles(self.token, searches)
-        if not results['data']:
-            logger.debug(u'Could not find subtitles for %r with token %s' % (searches, self.token))
-            return []
-        subtitles = []
-        for result in results['data']:
-            language = self.get_language(result['SubLanguageID'])
-            path = get_subtitle_path(filepath, language, self.config.multi)
-            confidence = 1 - float(self.confidence_order.index(result['MatchedBy'])) / float(len(self.confidence_order))
-            subtitle = ResultSubtitle(path, language, self.__class__.__name__.lower(), result['SubDownloadLink'],
-                                      release=to_unicode(result['SubFileName']), confidence=confidence)
-            subtitles.append(subtitle)
-        return subtitles
-
-    def list_checked(self, video, languages):
-        results = []
-        if video.exists:
-            results = self.query(video.path or video.release, languages, moviehash=video.hashes['OpenSubtitles'], size=str(video.size))
-        elif video.imdbid:
-            results = self.query(video.path or video.release, languages, imdbid=video.imdbid)
-        elif isinstance(video, Episode):
-            results = self.query(video.path or video.release, languages, query=video.series)
-        elif isinstance(video, Movie):
-            results = self.query(video.path or video.release, languages, query=video.title)
-        return results
-
-    def download(self, subtitle):
-        #TODO: Use OpenSubtitles DownloadSubtitles method
-        try:
-            self.download_file(subtitle.link, subtitle.path + '.gz')
-            with open(subtitle.path, 'wb') as dump:
-                gz = gzip.open(subtitle.path + '.gz')
-                dump.write(gz.read())
-                gz.close()
-        except Exception as e:
-            if os.path.exists(subtitle.path):
-                os.remove(subtitle.path)
-            raise DownloadFailedError(str(e))
-        finally:
-            if os.path.exists(subtitle.path + '.gz'):
-                os.remove(subtitle.path + '.gz')
-        return subtitle
-
-
-Service = OpenSubtitles

subliminal/services/podnapisi.py

@@ -1,110 +0,0 @@
-# -*- coding: utf-8 -*-
-# Copyright 2011-2012 Antoine Bertin <diaoulael@gmail.com>
-#
-# This file is part of subliminal.
-#
-# subliminal is free software; you can redistribute it and/or modify it under
-# the terms of the GNU Lesser General Public License as published by
-# the Free Software Foundation; either version 3 of the License, or
-# (at your option) any later version.
-#
-# subliminal is distributed in the hope that it will be useful,
-# but WITHOUT ANY WARRANTY; without even the implied warranty of
-# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
-# GNU Lesser General Public License for more details.
-#
-# You should have received a copy of the GNU Lesser General Public License
-# along with subliminal.  If not, see <http://www.gnu.org/licenses/>.
-from . import ServiceBase
-from ..exceptions import ServiceError, DownloadFailedError
-from ..language import language_set, Language
-from ..subtitles import get_subtitle_path, ResultSubtitle
-from ..utils import to_unicode
-from ..videos import Episode, Movie
-from hashlib import md5, sha256
-import logging
-import xmlrpclib
-
-
-logger = logging.getLogger(__name__)
-
-
-class Podnapisi(ServiceBase):
-    server_url = 'http://ssp.podnapisi.net:8000'
-    api_based = True
-    languages = language_set(['ar', 'be', 'bg', 'bs', 'ca', 'ca', 'cs', 'da', 'de', 'el', 'en',
-                              'es', 'et', 'fa', 'fi', 'fr', 'ga', 'he', 'hi', 'hr', 'hu', 'id',
-                              'is', 'it', 'ja', 'ko', 'lt', 'lv', 'mk', 'ms', 'nl', 'nn', 'pl',
-                              'pt', 'ro', 'ru', 'sk', 'sl', 'sq', 'sr', 'sv', 'th', 'tr', 'uk',
-                              'vi', 'zh', 'es-ar', 'pt-br'])
-    language_map = {'jp': Language('jpn'), Language('jpn'): 'jp',
-                    'gr': Language('gre'), Language('gre'): 'gr',
-                    'pb': Language('por-BR'), Language('por-BR'): 'pb',
-                    'ag': Language('spa-AR'), Language('spa-AR'): 'ag',
-                    'cyr': Language('srp')}
-    videos = [Episode, Movie]
-    require_video = True
-
-    def __init__(self, config=None):
-        super(Podnapisi, self).__init__(config)
-        self.server = xmlrpclib.ServerProxy(self.server_url)
-        self.token = None
-
-    def init(self):
-        super(Podnapisi, self).init()
-        result = self.server.initiate(self.user_agent)
-        if result['status'] != 200:
-            raise ServiceError('Initiate failed')
-        username = 'python_subliminal'
-        password = sha256(md5('XWFXQ6gE5Oe12rv4qxXX').hexdigest() + result['nonce']).hexdigest()
-        self.token = result['session']
-        result = self.server.authenticate(self.token, username, password)
-        if result['status'] != 200:
-            raise ServiceError('Authenticate failed')
-
-    def terminate(self):
-        super(Podnapisi, self).terminate()
-
-    def query(self, filepath, languages, moviehash):
-        results = self.server.search(self.token, [moviehash])
-        if results['status'] != 200:
-            logger.error('Search failed with error code %d' % results['status'])
-            return []
-        if not results['results'] or not results['results'][moviehash]['subtitles']:
-            logger.debug(u'Could not find subtitles for %r with token %s' % (moviehash, self.token))
-            return []
-        subtitles = []
-        for result in results['results'][moviehash]['subtitles']:
-            language = self.get_language(result['lang'])
-            if language not in languages:
-                continue
-            path = get_subtitle_path(filepath, language, self.config.multi)
-            subtitle = ResultSubtitle(path, language, self.__class__.__name__.lower(), result['id'],
-                                      release=to_unicode(result['release']), confidence=result['weight'])
-            subtitles.append(subtitle)
-        if not subtitles:
-            return []
-        # Convert weight to confidence
-        max_weight = float(max([s.confidence for s in subtitles]))
-        min_weight = float(min([s.confidence for s in subtitles]))
-        for subtitle in subtitles:
-            if max_weight == 0 and min_weight == 0:
-                subtitle.confidence = 1.0
-            else:
-                subtitle.confidence = (subtitle.confidence - min_weight) / (max_weight - min_weight)
-        return subtitles
-
-    def list_checked(self, video, languages):
-        results = self.query(video.path, languages, video.hashes['OpenSubtitles'])
-        return results
-
-    def download(self, subtitle):
-        results = self.server.download(self.token, [subtitle.link])
-        if results['status'] != 200:
-            raise DownloadFailedError()
-        subtitle.link = 'http://www.podnapisi.net/static/podnapisi/' + results['names'][0]['filename']
-        self.download_file(subtitle.link, subtitle.path)
-        return subtitle
-
-
-Service = Podnapisi

subliminal/services/subswiki.py

@@ -1,101 +0,0 @@
-# -*- coding: utf-8 -*-
-# Copyright 2011-2012 Antoine Bertin <diaoulael@gmail.com>
-#
-# This file is part of subliminal.
-#
-# subliminal is free software; you can redistribute it and/or modify it under
-# the terms of the GNU Lesser General Public License as published by
-# the Free Software Foundation; either version 3 of the License, or
-# (at your option) any later version.
-#
-# subliminal is distributed in the hope that it will be useful,
-# but WITHOUT ANY WARRANTY; without even the implied warranty of
-# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
-# GNU Lesser General Public License for more details.
-#
-# You should have received a copy of the GNU Lesser General Public License
-# along with subliminal.  If not, see <http://www.gnu.org/licenses/>.
-from . import ServiceBase
-from ..exceptions import ServiceError
-from ..language import language_set, Language
-from ..subtitles import get_subtitle_path, ResultSubtitle
-from ..videos import Episode, Movie
-from bs4 import BeautifulSoup
-from subliminal.utils import get_keywords, split_keyword
-import logging
-import re
-import urllib
-
-
-logger = logging.getLogger(__name__)
-
-
-class SubsWiki(ServiceBase):
-    server_url = 'http://www.subswiki.com'
-    api_based = False
-    languages = language_set(['eng-US', 'eng-GB', 'eng', 'fre', 'por-BR', 'por', 'spa-ES', u'spa', u'ita', u'cat'])
-    language_map = {u'Español': Language('spa'), u'Español (España)': Language('spa'), u'Español (Latinoamérica)': Language('spa'),
-                    u'Català': Language('cat'), u'Brazilian': Language('por-BR'), u'English (US)': Language('eng-US'),
-                    u'English (UK)': Language('eng-GB')}
-    language_code = 'name'
-    videos = [Episode, Movie]
-    require_video = False
-    release_pattern = re.compile('\nVersion (.+), ([0-9]+).([0-9])+ MBs')
-    required_features = ['permissive']
-
-    def list_checked(self, video, languages):
-        results = []
-        if isinstance(video, Episode):
-            results = self.query(video.path or video.release, languages, get_keywords(video.guess), series=video.series, season=video.season, episode=video.episode)
-        elif isinstance(video, Movie) and video.year:
-            results = self.query(video.path or video.release, languages, get_keywords(video.guess), movie=video.title, year=video.year)
-        return results
-
-    def query(self, filepath, languages, keywords=None, series=None, season=None, episode=None, movie=None, year=None):
-        if series and season and episode:
-            request_series = series.lower().replace(' ', '_')
-            if isinstance(request_series, unicode):
-                request_series = request_series.encode('utf-8')
-            logger.debug(u'Getting subtitles for %s season %d episode %d with languages %r' % (series, season, episode, languages))
-            r = self.session.get('%s/serie/%s/%s/%s/' % (self.server_url, urllib.quote(request_series), season, episode))
-            if r.status_code == 404:
-                logger.debug(u'Could not find subtitles for %s season %d episode %d with languages %r' % (series, season, episode, languages))
-                return []
-        elif movie and year:
-            request_movie = movie.title().replace(' ', '_')
-            if isinstance(request_movie, unicode):
-                request_movie = request_movie.encode('utf-8')
-            logger.debug(u'Getting subtitles for %s (%d) with languages %r' % (movie, year, languages))
-            r = self.session.get('%s/film/%s_(%d)' % (self.server_url, urllib.quote(request_movie), year))
-            if r.status_code == 404:
-                logger.debug(u'Could not find subtitles for %s (%d) with languages %r' % (movie, year, languages))
-                return []
-        else:
-            raise ServiceError('One or more parameter missing')
-        if r.status_code != 200:
-            logger.error(u'Request %s returned status code %d' % (r.url, r.status_code))
-            return []
-        soup = BeautifulSoup(r.content, self.required_features)
-        subtitles = []
-        for sub in soup('td', {'class': 'NewsTitle'}):
-            sub_keywords = split_keyword(self.release_pattern.search(sub.contents[1]).group(1).lower())
-            if not keywords & sub_keywords:
-                logger.debug(u'None of subtitle keywords %r in %r' % (sub_keywords, keywords))
-                continue
-            for html_language in sub.parent.parent.findAll('td', {'class': 'language'}):
-                language = self.get_language(html_language.string.strip())
-                if language not in languages:
-                    logger.debug(u'Language %r not in wanted languages %r' % (language, languages))
-                    continue
-                html_status = html_language.findNextSibling('td')
-                status = html_status.find('strong').string.strip()
-                if status != 'Completed':
-                    logger.debug(u'Wrong subtitle status %s' % status)
-                    continue
-                path = get_subtitle_path(filepath, language, self.config.multi)
-                subtitle = ResultSubtitle(path, language, self.__class__.__name__.lower(), '%s%s' % (self.server_url, html_status.findNext('td').find('a')['href']))
-                subtitles.append(subtitle)
-        return subtitles
-
-
-Service = SubsWiki

subliminal/services/subtitulos.py

@@ -1,88 +0,0 @@
-# -*- coding: utf-8 -*-
-# Copyright 2011-2012 Antoine Bertin <diaoulael@gmail.com>
-#
-# This file is part of subliminal.
-#
-# subliminal is free software; you can redistribute it and/or modify it under
-# the terms of the GNU Lesser General Public License as published by
-# the Free Software Foundation; either version 3 of the License, or
-# (at your option) any later version.
-#
-# subliminal is distributed in the hope that it will be useful,
-# but WITHOUT ANY WARRANTY; without even the implied warranty of
-# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
-# GNU Lesser General Public License for more details.
-#
-# You should have received a copy of the GNU Lesser General Public License
-# along with subliminal.  If not, see <http://www.gnu.org/licenses/>.
-from . import ServiceBase
-from ..language import language_set, Language
-from ..subtitles import get_subtitle_path, ResultSubtitle
-from ..videos import Episode
-from bs4 import BeautifulSoup
-from subliminal.utils import get_keywords, split_keyword
-import logging
-import re
-import unicodedata
-import urllib
-
-
-logger = logging.getLogger(__name__)
-
-
-class Subtitulos(ServiceBase):
-    server_url = 'http://www.subtitulos.es'
-    api_based = False
-    languages = language_set(['eng-US', 'eng-GB', 'eng', 'fre', 'por-BR', 'por', 'spa-ES', u'spa', u'ita', u'cat'])
-    language_map = {u'Español': Language('spa'), u'Español (España)': Language('spa'), u'Español (Latinoamérica)': Language('spa'),
-                    u'Català': Language('cat'), u'Brazilian': Language('por-BR'), u'English (US)': Language('eng-US'),
-                    u'English (UK)': Language('eng-GB'), 'Galego': Language('glg')}
-    language_code = 'name'
-    videos = [Episode]
-    require_video = False
-    required_features = ['permissive']
-    # the '.+' in the pattern for Version allows us to match both '&oacute;'
-    # and the 'ó' char directly. This is because now BS4 converts the html
-    # code chars into their equivalent unicode char
-    release_pattern = re.compile('Versi.+n (.+) ([0-9]+).([0-9])+ megabytes')
-
-    def list_checked(self, video, languages):
-        return self.query(video.path or video.release, languages, get_keywords(video.guess), video.series, video.season, video.episode)
-
-    def query(self, filepath, languages, keywords, series, season, episode):
-        request_series = series.lower().replace(' ', '_')
-        if isinstance(request_series, unicode):
-            request_series = unicodedata.normalize('NFKD', request_series).encode('ascii', 'ignore')
-        logger.debug(u'Getting subtitles for %s season %d episode %d with languages %r' % (series, season, episode, languages))
-        r = self.session.get('%s/%s/%sx%.2d' % (self.server_url, urllib.quote(request_series), season, episode))
-        if r.status_code == 404:
-            logger.debug(u'Could not find subtitles for %s season %d episode %d with languages %r' % (series, season, episode, languages))
-            return []
-        if r.status_code != 200:
-            logger.error(u'Request %s returned status code %d' % (r.url, r.status_code))
-            return []
-        soup = BeautifulSoup(r.content, self.required_features)
-        subtitles = []
-        for sub in soup('div', {'id': 'version'}):
-            sub_keywords = split_keyword(self.release_pattern.search(sub.find('p', {'class': 'title-sub'}).contents[1]).group(1).lower())
-            if not keywords & sub_keywords:
-                logger.debug(u'None of subtitle keywords %r in %r' % (sub_keywords, keywords))
-                continue
-            for html_language in sub.findAllNext('ul', {'class': 'sslist'}):
-                language = self.get_language(html_language.findNext('li', {'class': 'li-idioma'}).find('strong').contents[0].string.strip())
-                if language not in languages:
-                    logger.debug(u'Language %r not in wanted languages %r' % (language, languages))
-                    continue
-                html_status = html_language.findNext('li', {'class': 'li-estado green'})
-                status = html_status.contents[0].string.strip()
-                if status != 'Completado':
-                    logger.debug(u'Wrong subtitle status %s' % status)
-                    continue
-                path = get_subtitle_path(filepath, language, self.config.multi)
-                subtitle = ResultSubtitle(path, language, self.__class__.__name__.lower(), html_status.findNext('span', {'class': 'descargar green'}).find('a')['href'],
-                                          keywords=sub_keywords)
-                subtitles.append(subtitle)
-        return subtitles
-
-
-Service = Subtitulos

subliminal/services/thesubdb.py

@@ -1,63 +0,0 @@
-# -*- coding: utf-8 -*-
-# Copyright 2011-2012 Antoine Bertin <diaoulael@gmail.com>
-#
-# This file is part of subliminal.
-#
-# subliminal is free software; you can redistribute it and/or modify it under
-# the terms of the GNU Lesser General Public License as published by
-# the Free Software Foundation; either version 3 of the License, or
-# (at your option) any later version.
-#
-# subliminal is distributed in the hope that it will be useful,
-# but WITHOUT ANY WARRANTY; without even the implied warranty of
-# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
-# GNU Lesser General Public License for more details.
-#
-# You should have received a copy of the GNU Lesser General Public License
-# along with subliminal.  If not, see <http://www.gnu.org/licenses/>.
-from . import ServiceBase
-from ..language import language_set
-from ..subtitles import get_subtitle_path, ResultSubtitle
-from ..videos import Episode, Movie, UnknownVideo
-import logging
-
-
-logger = logging.getLogger(__name__)
-
-
-class TheSubDB(ServiceBase):
-    server_url = 'http://api.thesubdb.com'
-    user_agent = 'SubDB/1.0 (subliminal/0.6; https://github.com/Diaoul/subliminal)'
-    api_based = True
-    # Source: http://api.thesubdb.com/?action=languages
-    languages = language_set(['af', 'cs', 'da', 'de', 'en', 'es', 'fi', 'fr', 'hu', 'id', 'it',
-                              'la', 'nl', 'no', 'oc', 'pl', 'pt', 'ro', 'ru', 'sl', 'sr', 'sv',
-                              'tr'])
-    videos = [Movie, Episode, UnknownVideo]
-    require_video = True
-
-    def list_checked(self, video, languages):
-        return self.query(video.path, video.hashes['TheSubDB'], languages)
-
-    def query(self, filepath, moviehash, languages):
-        r = self.session.get(self.server_url, params={'action': 'search', 'hash': moviehash})
-        if r.status_code == 404:
-            logger.debug(u'Could not find subtitles for hash %s' % moviehash)
-            return []
-        if r.status_code != 200:
-            logger.error(u'Request %s returned status code %d' % (r.url, r.status_code))
-            return []
-        available_languages = language_set(r.content.split(','))
-        languages &= available_languages
-        if not languages:
-            logger.debug(u'Could not find subtitles for hash %s with languages %r (only %r available)' % (moviehash, languages, available_languages))
-            return []
-        subtitles = []
-        for language in languages:
-            path = get_subtitle_path(filepath, language, self.config.multi)
-            subtitle = ResultSubtitle(path, language, self.__class__.__name__.lower(), '%s?action=download&hash=%s&language=%s' % (self.server_url, moviehash, language.alpha2))
-            subtitles.append(subtitle)
-        return subtitles
-
-
-Service = TheSubDB

subliminal/services/tvsubtitles.py

@@ -1,142 +0,0 @@
-# -*- coding: utf-8 -*-
-# Copyright 2012 Nicolas Wack <wackou@gmail.com>
-#
-# This file is part of subliminal.
-#
-# subliminal is free software; you can redistribute it and/or modify it under
-# the terms of the GNU Lesser General Public License as published by
-# the Free Software Foundation; either version 3 of the License, or
-# (at your option) any later version.
-#
-# subliminal is distributed in the hope that it will be useful,
-# but WITHOUT ANY WARRANTY; without even the implied warranty of
-# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
-# GNU Lesser General Public License for more details.
-#
-# You should have received a copy of the GNU Lesser General Public License
-# along with subliminal.  If not, see <http://www.gnu.org/licenses/>.
-from . import ServiceBase
-from ..cache import cachedmethod
-from ..language import language_set, Language
-from ..subtitles import get_subtitle_path, ResultSubtitle
-from ..utils import get_keywords
-from ..videos import Episode
-from bs4 import BeautifulSoup
-import logging
-import re
-
-
-logger = logging.getLogger(__name__)
-
-
-def match(pattern, string):
-    try:
-        return re.search(pattern, string).group(1)
-    except AttributeError:
-        logger.debug(u'Could not match %r on %r' % (pattern, string))
-        return None
-
-
-class TvSubtitles(ServiceBase):
-    server_url = 'http://www.tvsubtitles.net'
-    api_based = False
-    languages = language_set(['ar', 'bg', 'cs', 'da', 'de', 'el', 'en', 'es', 'fi', 'fr', 'hu',
-                              'it', 'ja', 'ko', 'nl', 'pl', 'pt', 'ro', 'ru', 'sv', 'tr', 'uk',
-                              'zh', 'pt-br'])
-    #TODO: Find more exceptions
-    language_map = {'gr': Language('gre'), 'cz': Language('cze'), 'ua': Language('ukr'),
-                    'cn': Language('chi')}
-    videos = [Episode]
-    require_video = False
-    required_features = ['permissive']
-
-    @cachedmethod
-    def get_likely_series_id(self, name):
-        r = self.session.post('%s/search.php' % self.server_url, data={'q': name})
-        soup = BeautifulSoup(r.content, self.required_features)
-        maindiv = soup.find('div', 'left')
-        results = []
-        for elem in maindiv.find_all('li'):
-            sid = int(match('tvshow-([0-9]+)\.html', elem.a['href']))
-            show_name = match('(.*) \(', elem.a.text)
-            results.append((show_name, sid))
-        #TODO: pick up the best one in a smart way
-        result = results[0]
-        return result[1]
-
-    @cachedmethod
-    def get_episode_id(self, series_id, season, number):
-        """Get the TvSubtitles id for the given episode. Raises KeyError if none
-        could be found."""
-        # download the page of the season, contains ids for all episodes
-        episode_id = None
-        r = self.session.get('%s/tvshow-%d-%d.html' % (self.server_url, series_id, season))
-        soup = BeautifulSoup(r.content, self.required_features)
-        table = soup.find('table', id='table5')
-        for row in table.find_all('tr'):
-            cells = row.find_all('td')
-            if not cells:
-                continue
-            episode_number = match('x([0-9]+)', cells[0].text)
-            if not episode_number:
-                continue
-            episode_number = int(episode_number)
-            episode_id = int(match('episode-([0-9]+)', cells[1].a['href']))
-            # we could just return the id of the queried episode, but as we
-            # already downloaded the whole page we might as well fill in the
-            # information for all the episodes of the season
-            self.cache_for(self.get_episode_id, args=(series_id, season, episode_number), result=episode_id)
-        # raises KeyError if not found
-        return self.cached_value(self.get_episode_id, args=(series_id, season, number))
-
-    # Do not cache this method in order to always check for the most recent
-    # subtitles
-    def get_sub_ids(self, episode_id):
-        subids = []
-        r = self.session.get('%s/episode-%d.html' % (self.server_url, episode_id))
-        epsoup = BeautifulSoup(r.content, self.required_features)
-        for subdiv in epsoup.find_all('a'):
-            if 'href' not in subdiv.attrs or not subdiv['href'].startswith('/subtitle'):
-                continue
-            subid = int(match('([0-9]+)', subdiv['href']))
-            lang = self.get_language(match('flags/(.*).gif', subdiv.img['src']))
-            result = {'subid': subid, 'language': lang}
-            for p in subdiv.find_all('p'):
-                if 'alt' in p.attrs and p['alt'] == 'rip':
-                    result['rip'] = p.text.strip()
-                if 'alt' in p.attrs and p['alt'] == 'release':
-                    result['release'] = p.text.strip()
-            subids.append(result)
-        return subids
-
-    def list_checked(self, video, languages):
-        return self.query(video.path or video.release, languages, get_keywords(video.guess), video.series, video.season, video.episode)
-
-    def query(self, filepath, languages, keywords, series, season, episode):
-        logger.debug(u'Getting subtitles for %s season %d episode %d with languages %r' % (series, season, episode, languages))
-        self.init_cache()
-        sid = self.get_likely_series_id(series.lower())
-        try:
-            ep_id = self.get_episode_id(sid, season, episode)
-        except KeyError:
-            logger.debug(u'Could not find episode id for %s season %d episode %d' % (series, season, episode))
-            return []
-        subids = self.get_sub_ids(ep_id)
-        # filter the subtitles with our queried languages
-        subtitles = []
-        for subid in subids:
-            language = subid['language']
-            if language not in languages:
-                continue
-            path = get_subtitle_path(filepath, language, self.config.multi)
-            subtitle = ResultSubtitle(path, language, self.__class__.__name__.lower(), '%s/download-%d.html' % (self.server_url, subid['subid']),
-                                      keywords=[subid['rip'], subid['release']])
-            subtitles.append(subtitle)
-        return subtitles
-
-    def download(self, subtitle):
-        self.download_zip_file(subtitle.link, subtitle.path)
-        return subtitle
-
-
-Service = TvSubtitles

subliminal/subtitle.py

@@ -0,0 +1,253 @@
+# -*- coding: utf-8 -*-
+import codecs
+import logging
+import os
+
+import chardet
+import pysrt
+
+from .video import Episode, Movie
+from .utils import sanitize, sanitize_release_group
+
+
+logger = logging.getLogger(__name__)
+
+#: Subtitle extensions
+SUBTITLE_EXTENSIONS = ('.srt', '.sub', '.smi', '.txt', '.ssa', '.ass', '.mpl')
+
+
+class Subtitle(object):
+    """Base class for subtitle.
+
+    :param language: language of the subtitle.
+    :type language: :class:`~babelfish.language.Language`
+    :param bool hearing_impaired: whether or not the subtitle is hearing impaired.
+    :param page_link: URL of the web page from which the subtitle can be downloaded.
+    :type page_link: str
+    :param encoding: Text encoding of the subtitle.
+    :type encoding: str
+
+    """
+    #: Name of the provider that returns that class of subtitle
+    provider_name = ''
+
+    def __init__(self, language, hearing_impaired=False, page_link=None, encoding=None):
+        #: Language of the subtitle
+        self.language = language
+
+        #: Whether or not the subtitle is hearing impaired
+        self.hearing_impaired = hearing_impaired
+
+        #: URL of the web page from which the subtitle can be downloaded
+        self.page_link = page_link
+
+        #: Content as bytes
+        self.content = None
+
+        #: Encoding to decode with when accessing :attr:`text`
+        self.encoding = None
+
+        # validate the encoding
+        if encoding:
+            try:
+                self.encoding = codecs.lookup(encoding).name
+            except (TypeError, LookupError):
+                logger.debug('Unsupported encoding %s', encoding)
+
+    @property
+    def id(self):
+        """Unique identifier of the subtitle"""
+        raise NotImplementedError
+
+    @property
+    def text(self):
+        """Content as string
+
+        If :attr:`encoding` is None, the encoding is guessed with :meth:`guess_encoding`
+
+        """
+        if not self.content:
+            return
+
+        if self.encoding:
+            return self.content.decode(self.encoding, errors='replace')
+
+        return self.content.decode(self.guess_encoding(), errors='replace')
+
+    def is_valid(self):
+        """Check if a :attr:`text` is a valid SubRip format.
+
+        :return: whether or not the subtitle is valid.
+        :rtype: bool
+
+        """
+        if not self.text:
+            return False
+
+        try:
+            pysrt.from_string(self.text, error_handling=pysrt.ERROR_RAISE)
+        except pysrt.Error as e:
+            if e.args[0] < 80:
+                return False
+
+        return True
+
+    def guess_encoding(self):
+        """Guess encoding using the language, falling back on chardet.
+
+        :return: the guessed encoding.
+        :rtype: str
+
+        """
+        logger.info('Guessing encoding for language %s', self.language)
+
+        # always try utf-8 first
+        encodings = ['utf-8']
+
+        # add language-specific encodings
+        if self.language.alpha3 == 'zho':
+            encodings.extend(['gb18030', 'big5'])
+        elif self.language.alpha3 == 'jpn':
+            encodings.append('shift-jis')
+        elif self.language.alpha3 == 'ara':
+            encodings.append('windows-1256')
+        elif self.language.alpha3 == 'heb':
+            encodings.append('windows-1255')
+        elif self.language.alpha3 == 'tur':
+            encodings.extend(['iso-8859-9', 'windows-1254'])
+        elif self.language.alpha3 == 'pol':
+            # Eastern European Group 1
+            encodings.extend(['windows-1250'])
+        elif self.language.alpha3 == 'bul':
+            # Eastern European Group 2
+            encodings.extend(['windows-1251'])
+        else:
+            # Western European (windows-1252)
+            encodings.append('latin-1')
+
+        # try to decode
+        logger.debug('Trying encodings %r', encodings)
+        for encoding in encodings:
+            try:
+                self.content.decode(encoding)
+            except UnicodeDecodeError:
+                pass
+            else:
+                logger.info('Guessed encoding %s', encoding)
+                return encoding
+
+        logger.warning('Could not guess encoding from language')
+
+        # fallback on chardet
+        encoding = chardet.detect(self.content)['encoding']
+        logger.info('Chardet found encoding %s', encoding)
+
+        return encoding
+
+    def get_matches(self, video):
+        """Get the matches against the `video`.
+
+        :param video: the video to get the matches with.
+        :type video: :class:`~subliminal.video.Video`
+        :return: matches of the subtitle.
+        :rtype: set
+
+        """
+        raise NotImplementedError
+
+    def __hash__(self):
+        return hash(self.provider_name + '-' + self.id)
+
+    def __repr__(self):
+        return '<%s %r [%s]>' % (self.__class__.__name__, self.id, self.language)
+
+
+def get_subtitle_path(video_path, language=None, extension='.srt'):
+    """Get the subtitle path using the `video_path` and `language`.
+
+    :param str video_path: path to the video.
+    :param language: language of the subtitle to put in the path.
+    :type language: :class:`~babelfish.language.Language`
+    :param str extension: extension of the subtitle.
+    :return: path of the subtitle.
+    :rtype: str
+
+    """
+    subtitle_root = os.path.splitext(video_path)[0]
+
+    if language:
+        subtitle_root += '.' + str(language)
+
+    return subtitle_root + extension
+
+
+def guess_matches(video, guess, partial=False):
+    """Get matches between a `video` and a `guess`.
+
+    If a guess is `partial`, the absence information won't be counted as a match.
+
+    :param video: the video.
+    :type video: :class:`~subliminal.video.Video`
+    :param guess: the guess.
+    :type guess: dict
+    :param bool partial: whether or not the guess is partial.
+    :return: matches between the `video` and the `guess`.
+    :rtype: set
+
+    """
+    matches = set()
+    if isinstance(video, Episode):
+        # series
+        if video.series and 'title' in guess and sanitize(guess['title']) == sanitize(video.series):
+            matches.add('series')
+        # title
+        if video.title and 'episode_title' in guess and sanitize(guess['episode_title']) == sanitize(video.title):
+            matches.add('title')
+        # season
+        if video.season and 'season' in guess and guess['season'] == video.season:
+            matches.add('season')
+        # episode
+        if video.episode and 'episode' in guess and guess['episode'] == video.episode:
+            matches.add('episode')
+        # year
+        if video.year and 'year' in guess and guess['year'] == video.year:
+            matches.add('year')
+        # count "no year" as an information
+        if not partial and video.original_series and 'year' not in guess:
+            matches.add('year')
+    elif isinstance(video, Movie):
+        # year
+        if video.year and 'year' in guess and guess['year'] == video.year:
+            matches.add('year')
+        # title
+        if video.title and 'title' in guess and sanitize(guess['title']) == sanitize(video.title):
+            matches.add('title')
+    # release_group
+    if (video.release_group and 'release_group' in guess and
+            sanitize_release_group(guess['release_group']) == sanitize_release_group(video.release_group)):
+        matches.add('release_group')
+    # resolution
+    if video.resolution and 'screen_size' in guess and guess['screen_size'] == video.resolution:
+        matches.add('resolution')
+    # format
+    if video.format and 'format' in guess and guess['format'].lower() == video.format.lower():
+        matches.add('format')
+    # video_codec
+    if video.video_codec and 'video_codec' in guess and guess['video_codec'] == video.video_codec:
+        matches.add('video_codec')
+    # audio_codec
+    if video.audio_codec and 'audio_codec' in guess and guess['audio_codec'] == video.audio_codec:
+        matches.add('audio_codec')
+
+    return matches
+
+
+def fix_line_ending(content):
+    """Fix line ending of `content` by changing it to \n.
+
+    :param bytes content: content of the subtitle.
+    :return: the content with fixed line endings.
+    :rtype: bytes
+
+    """
+    return content.replace(b'\r\n', b'\n').replace(b'\r', b'\n')

subliminal/subtitles.py

@@ -1,149 +0,0 @@
-# -*- coding: utf-8 -*-
-# Copyright 2011-2012 Antoine Bertin <diaoulael@gmail.com>
-#
-# This file is part of subliminal.
-#
-# subliminal is free software; you can redistribute it and/or modify it under
-# the terms of the GNU Lesser General Public License as published by
-# the Free Software Foundation; either version 3 of the License, or
-# (at your option) any later version.
-#
-# subliminal is distributed in the hope that it will be useful,
-# but WITHOUT ANY WARRANTY; without even the implied warranty of
-# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
-# GNU Lesser General Public License for more details.
-#
-# You should have received a copy of the GNU Lesser General Public License
-# along with subliminal.  If not, see <http://www.gnu.org/licenses/>.
-from .language import Language
-from .utils import to_unicode
-import os.path
-
-
-__all__ = ['Subtitle', 'EmbeddedSubtitle', 'ExternalSubtitle', 'ResultSubtitle', 'get_subtitle_path']
-
-#: Subtitles extensions
-EXTENSIONS = ['.srt', '.sub', '.txt']
-
-
-class Subtitle(object):
-    """Base class for subtitles
-
-    :param string path: path to the subtitle
-    :param language: language of the subtitle
-    :type language: :class:`~subliminal.language.Language`
-
-    """
-    def __init__(self, path, language):
-        if not isinstance(language, Language):
-            raise TypeError('%r is not an instance of Language')
-        self.path = path
-        self.language = language
-
-    @property
-    def exists(self):
-        """Whether the subtitle exists or not"""
-        if self.path:
-            return os.path.exists(self.path)
-        return False
-
-    def __unicode__(self):
-        return to_unicode(self.path)
-
-    def __str__(self):
-        return unicode(self).encode('utf-8')
-
-    def __repr__(self):
-        return '%s(%s, %s)' % (self.__class__.__name__, self, self.language)
-
-
-class EmbeddedSubtitle(Subtitle):
-    """Subtitle embedded in a container
-
-    :param string path: path to the subtitle
-    :param language: language of the subtitle
-    :type language: :class:`~subliminal.language.Language`
-    :param int track_id: id of the subtitle track in the container
-
-    """
-    def __init__(self, path, language, track_id):
-        super(EmbeddedSubtitle, self).__init__(path, language)
-        self.track_id = track_id
-
-    @classmethod
-    def from_enzyme(cls, path, subtitle):
-        language = Language(subtitle.language, strict=False)
-        return cls(path, language, subtitle.trackno)
-
-
-class ExternalSubtitle(Subtitle):
-    """Subtitle in a file next to the video file"""
-    @classmethod
-    def from_path(cls, path):
-        """Create an :class:`ExternalSubtitle` from path"""
-        extension = None
-        for e in EXTENSIONS:
-            if path.endswith(e):
-                extension = e
-                break
-        if extension is None:
-            raise ValueError('Not a supported subtitle extension')
-        language = Language(os.path.splitext(path[:len(path) - len(extension)])[1][1:], strict=False)
-        return cls(path, language)
-
-
-class ResultSubtitle(ExternalSubtitle):
-    """Subtitle found using :mod:`~subliminal.services`
-
-    :param string path: path to the subtitle
-    :param language: language of the subtitle
-    :type language: :class:`~subliminal.language.Language`
-    :param string service: name of the service
-    :param string link: download link for the subtitle
-    :param string release: release name of the video
-    :param float confidence: confidence that the subtitle matches the video according to the service
-    :param set keywords: keywords that describe the subtitle
-
-    """
-    def __init__(self, path, language, service, link, release=None, confidence=1, keywords=None):
-        super(ResultSubtitle, self).__init__(path, language)
-        self.service = service
-        self.link = link
-        self.release = release
-        self.confidence = confidence
-        self.keywords = keywords or set()
-
-    @property
-    def single(self):
-        """Whether this is a single subtitle or not. A single subtitle does not have
-        a language indicator in its file name
-
-        :rtype: bool
-
-        """
-        return self.language == Language('Undetermined')
-
-    def __repr__(self):
-        if not self.release:
-            return 'ResultSubtitle(%s, %s, %s, %.2f)' % (self.path, self.language, self.service, self.confidence)
-        return 'ResultSubtitle(%s, %s, %s, %.2f, release=%s)' % (self.path, self.language, self.service, self.confidence, self.release.encode('ascii', 'ignore'))
-
-
-def get_subtitle_path(video_path, language, multi):
-    """Create the subtitle path from the given video path using language if multi
-
-    :param string video_path: path to the video
-    :param language: language of the subtitle
-    :type language: :class:`~subliminal.language.Language`
-    :param bool multi: whether to use multi language naming or not
-    :return: path of the subtitle
-    :rtype: string
-
-    """
-    if not os.path.exists(video_path):
-        path = os.path.splitext(os.path.basename(video_path))[0]
-    else:
-        path = os.path.splitext(video_path)[0]
-    if multi and language:
-        return path + '.%s%s' % (language.alpha2, EXTENSIONS[0])
-    return path + '%s' % EXTENSIONS[0]

subliminal/tasks.py

@@ -1,68 +0,0 @@
-# -*- coding: utf-8 -*-
-# Copyright 2011-2012 Antoine Bertin <diaoulael@gmail.com>
-#
-# This file is part of subliminal.
-#
-# subliminal is free software; you can redistribute it and/or modify it under
-# the terms of the GNU Lesser General Public License as published by
-# the Free Software Foundation; either version 3 of the License, or
-# (at your option) any later version.
-#
-# subliminal is distributed in the hope that it will be useful,
-# but WITHOUT ANY WARRANTY; without even the implied warranty of
-# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
-# GNU Lesser General Public License for more details.
-#
-# You should have received a copy of the GNU Lesser General Public License
-# along with subliminal.  If not, see <http://www.gnu.org/licenses/>.
-__all__ = ['Task', 'ListTask', 'DownloadTask', 'StopTask']
-
-
-class Task(object):
-    """Base class for tasks to use in subliminal"""
-    pass
-
-
-class ListTask(Task):
-    """List task used by the worker to search for subtitles
-
-    :param video: video to search subtitles for
-    :type video: :class:`~subliminal.videos.Video`
-    :param list languages: languages to search for
-    :param string service: name of the service to use
-    :param config: configuration for the service
-    :type config: :class:`~subliminal.services.ServiceConfig`
-
-    """
-    def __init__(self, video, languages, service, config):
-        super(ListTask, self).__init__()
-        self.video = video
-        self.service = service
-        self.languages = languages
-        self.config = config
-
-    def __repr__(self):
-        return 'ListTask(%r, %r, %s, %r)' % (self.video, self.languages, self.service, self.config)
-
-
-class DownloadTask(Task):
-    """Download task used by the worker to download subtitles
-
-    :param video: video to download subtitles for
-    :type video: :class:`~subliminal.videos.Video`
-    :param subtitles: subtitles to download in order of preference
-    :type subtitles: list of :class:`~subliminal.subtitles.Subtitle`
-
-    """
-    def __init__(self, video, subtitles):
-        super(DownloadTask, self).__init__()
-        self.video = video
-        self.subtitles = subtitles
-
-    def __repr__(self):
-        return 'DownloadTask(%r, %r)' % (self.video, self.subtitles)
-
-
-class StopTask(Task):
-    """Stop task that will stop the worker"""
-    pass

subliminal/utils.py

@@ -1,69 +1,152 @@
 # -*- coding: utf-8 -*-
-# Copyright 2011-2012 Antoine Bertin <diaoulael@gmail.com>
-#
-# This file is part of subliminal.
-#
-# subliminal is free software; you can redistribute it and/or modify it under
-# the terms of the GNU Lesser General Public License as published by
-# the Free Software Foundation; either version 3 of the License, or
-# (at your option) any later version.
-#
-# subliminal is distributed in the hope that it will be useful,
-# but WITHOUT ANY WARRANTY; without even the implied warranty of
-# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
-# GNU Lesser General Public License for more details.
-#
-# You should have received a copy of the GNU Lesser General Public License
-# along with subliminal.  If not, see <http://www.gnu.org/licenses/>.
+from datetime import datetime
+import hashlib
+import os
 import re
+import struct
 
 
-__all__ = ['get_keywords', 'split_keyword', 'to_unicode']
+def hash_opensubtitles(video_path):
+    """Compute a hash using OpenSubtitles' algorithm.
 
-
-def get_keywords(guess):
-    """Retrieve keywords from guessed informations
-
-    :param guess: guessed informations
-    :type guess: :class:`guessit.guess.Guess`
-    :return: lower case alphanumeric keywords
-    :rtype: set
+    :param str video_path: path of the video.
+    :return: the hash.
+    :rtype: str
 
     """
-    keywords = set()
-    for k in ['releaseGroup', 'screenSize', 'videoCodec', 'format']:
-        if k in guess:
-            keywords = keywords | split_keyword(guess[k].lower())
-    return keywords
+    bytesize = struct.calcsize(b'<q')
+    with open(video_path, 'rb') as f:
+        filesize = os.path.getsize(video_path)
+        filehash = filesize
+        if filesize < 65536 * 2:
+            return
+        for _ in range(65536 // bytesize):
+            filebuffer = f.read(bytesize)
+            (l_value,) = struct.unpack(b'<q', filebuffer)
+            filehash += l_value
+            filehash &= 0xFFFFFFFFFFFFFFFF  # to remain as 64bit number
+        f.seek(max(0, filesize - 65536), 0)
+        for _ in range(65536 // bytesize):
+            filebuffer = f.read(bytesize)
+            (l_value,) = struct.unpack(b'<q', filebuffer)
+            filehash += l_value
+            filehash &= 0xFFFFFFFFFFFFFFFF
+    returnedhash = '%016x' % filehash
+
+    return returnedhash
 
 
-def split_keyword(keyword):
-    """Split a keyword in multiple ones on any non-alphanumeric character
+def hash_thesubdb(video_path):
+    """Compute a hash using TheSubDB's algorithm.
 
-    :param string keyword: keyword
-    :return: keywords
-    :rtype: set
+    :param str video_path: path of the video.
+    :return: the hash.
+    :rtype: str
 
     """
-    split = set(re.findall(r'\w+', keyword))
-    return split
+    readsize = 64 * 1024
+    if os.path.getsize(video_path) < readsize:
+        return
+    with open(video_path, 'rb') as f:
+        data = f.read(readsize)
+        f.seek(-readsize, os.SEEK_END)
+        data += f.read(readsize)
+
+    return hashlib.md5(data).hexdigest()
 
 
-def to_unicode(data):
-    """Convert a basestring to unicode
+def hash_napiprojekt(video_path):
+    """Compute a hash using NapiProjekt's algorithm.
 
-    :param basestring data: data to decode
-    :return: data as unicode
-    :rtype: unicode
+    :param str video_path: path of the video.
+    :return: the hash.
+    :rtype: str
 
     """
-    if not isinstance(data, basestring):
-        raise ValueError('Basestring expected')
-    if isinstance(data, unicode):
-        return data
-    for encoding in ('utf-8', 'latin-1'):
-        try:
-            return unicode(data, encoding)
-        except UnicodeDecodeError:
-            pass
-    return unicode(data, 'utf-8', 'replace')
+    readsize = 1024 * 1024 * 10
+    with open(video_path, 'rb') as f:
+        data = f.read(readsize)
+    return hashlib.md5(data).hexdigest()
+
+
+def hash_shooter(video_path):
+    """Compute a hash using Shooter's algorithm
+
+    :param string video_path: path of the video
+    :return: the hash
+    :rtype: string
+
+    """
+    filesize = os.path.getsize(video_path)
+    readsize = 4096
+    if os.path.getsize(video_path) < readsize * 2:
+        return None
+    offsets = (readsize, filesize // 3 * 2, filesize // 3, filesize - readsize * 2)
+    filehash = []
+    with open(video_path, 'rb') as f:
+        for offset in offsets:
+            f.seek(offset)
+            filehash.append(hashlib.md5(f.read(readsize)).hexdigest())
+    return ';'.join(filehash)
+
+
+def sanitize(string, ignore_characters=None):
+    """Sanitize a string to strip special characters.
+
+    :param str string: the string to sanitize.
+    :param set ignore_characters: characters to ignore.
+    :return: the sanitized string.
+    :rtype: str
+
+    """
+    # only deal with strings
+    if string is None:
+        return
+
+    ignore_characters = ignore_characters or set()
+
+    # replace some characters with one space
+    characters = {'-', ':', '(', ')', '.'} - ignore_characters
+    if characters:
+        string = re.sub(r'[%s]' % re.escape(''.join(characters)), ' ', string)
+
+    # remove some characters
+    characters = {'\''} - ignore_characters
+    if characters:
+        string = re.sub(r'[%s]' % re.escape(''.join(characters)), '', string)
+
+    # replace multiple spaces with one
+    string = re.sub(r'\s+', ' ', string)
+
+    # strip and lower case
+    return string.strip().lower()
+
+
+def sanitize_release_group(string):
+    """Sanitize a `release_group` string to remove content in square brackets.
+
+    :param str string: the release group to sanitize.
+    :return: the sanitized release group.
+    :rtype: str
+
+    """
+    # only deal with strings
+    if string is None:
+        return
+
+    # remove content in square brackets
+    string = re.sub(r'\[\w+\]', '', string)
+
+    # strip and lower case
+    return string.strip().lower()
+
+
+def timestamp(date):
+    """Get the timestamp of the `date`, python2/3 compatible
+
+    :param datetime.datetime date: the utc date.
+    :return: the timestamp of the date.
+    :rtype: float
+
+    """
+    return (date - datetime(1970, 1, 1)).total_seconds()

subliminal/video.py

@@ -0,0 +1,221 @@
+# -*- coding: utf-8 -*-
+from __future__ import division
+from datetime import datetime, timedelta
+import logging
+import os
+
+from guessit import guessit
+
+logger = logging.getLogger(__name__)
+
+#: Video extensions
+VIDEO_EXTENSIONS = ('.3g2', '.3gp', '.3gp2', '.3gpp', '.60d', '.ajp', '.asf', '.asx', '.avchd', '.avi', '.bik',
+                    '.bix', '.box', '.cam', '.dat', '.divx', '.dmf', '.dv', '.dvr-ms', '.evo', '.flc', '.fli',
+                    '.flic', '.flv', '.flx', '.gvi', '.gvp', '.h264', '.m1v', '.m2p', '.m2ts', '.m2v', '.m4e',
+                    '.m4v', '.mjp', '.mjpeg', '.mjpg', '.mkv', '.moov', '.mov', '.movhd', '.movie', '.movx', '.mp4',
+                    '.mpe', '.mpeg', '.mpg', '.mpv', '.mpv2', '.mxf', '.nsv', '.nut', '.ogg', '.ogm', '.omf', '.ps',
+                    '.qt', '.ram', '.rm', '.rmvb', '.swf', '.ts', '.vfw', '.vid', '.video', '.viv', '.vivo', '.vob',
+                    '.vro', '.wm', '.wmv', '.wmx', '.wrap', '.wvx', '.wx', '.x264', '.xvid')
+
+
+class Video(object):
+    """Base class for videos.
+
+    Represent a video, existing or not.
+
+    :param str name: name or path of the video.
+    :param str format: format of the video (HDTV, WEB-DL, BluRay, ...).
+    :param str release_group: release group of the video.
+    :param str resolution: resolution of the video stream (480p, 720p, 1080p or 1080i).
+    :param str video_codec: codec of the video stream.
+    :param str audio_codec: codec of the main audio stream.
+    :param str imdb_id: IMDb id of the video.
+    :param dict hashes: hashes of the video file by provider names.
+    :param int size: size of the video file in bytes.
+    :param set subtitle_languages: existing subtitle languages.
+
+    """
+    def __init__(self, name, format=None, release_group=None, resolution=None, video_codec=None, audio_codec=None,
+                 imdb_id=None, hashes=None, size=None, subtitle_languages=None):
+        #: Name or path of the video
+        self.name = name
+
+        #: Format of the video (HDTV, WEB-DL, BluRay, ...)
+        self.format = format
+
+        #: Release group of the video
+        self.release_group = release_group
+
+        #: Resolution of the video stream (480p, 720p, 1080p or 1080i)
+        self.resolution = resolution
+
+        #: Codec of the video stream
+        self.video_codec = video_codec
+
+        #: Codec of the main audio stream
+        self.audio_codec = audio_codec
+
+        #: IMDb id of the video
+        self.imdb_id = imdb_id
+
+        #: Hashes of the video file by provider names
+        self.hashes = hashes or {}
+
+        #: Size of the video file in bytes
+        self.size = size
+
+        #: Existing subtitle languages
+        self.subtitle_languages = subtitle_languages or set()
+
+    @property
+    def exists(self):
+        """Test whether the video exists"""
+        return os.path.exists(self.name)
+
+    @property
+    def age(self):
+        """Age of the video"""
+        if self.exists:
+            return datetime.utcnow() - datetime.utcfromtimestamp(os.path.getmtime(self.name))
+
+        return timedelta()
+
+    @classmethod
+    def fromguess(cls, name, guess):
+        """Create an :class:`Episode` or a :class:`Movie` with the given `name` based on the `guess`.
+
+        :param str name: name of the video.
+        :param dict guess: guessed data.
+        :raise: :class:`ValueError` if the `type` of the `guess` is invalid
+
+        """
+        if guess['type'] == 'episode':
+            return Episode.fromguess(name, guess)
+
+        if guess['type'] == 'movie':
+            return Movie.fromguess(name, guess)
+
+        raise ValueError('The guess must be an episode or a movie guess')
+
+    @classmethod
+    def fromname(cls, name):
+        """Shortcut for :meth:`fromguess` with a `guess` guessed from the `name`.
+
+        :param str name: name of the video.
+
+        """
+        return cls.fromguess(name, guessit(name))
+
+    def __repr__(self):
+        return '<%s [%r]>' % (self.__class__.__name__, self.name)
+
+    def __hash__(self):
+        return hash(self.name)
+
+
+class Episode(Video):
+    """Episode :class:`Video`.
+
+    :param str series: series of the episode.
+    :param int season: season number of the episode.
+    :param int episode: episode number of the episode.
+    :param str title: title of the episode.
+    :param int year: year of the series.
+    :param bool original_series: whether the series is the first with this name.
+    :param int tvdb_id: TVDB id of the episode.
+    :param \*\*kwargs: additional parameters for the :class:`Video` constructor.
+
+    """
+    def __init__(self, name, series, season, episode, title=None, year=None, original_series=True, tvdb_id=None,
+                 series_tvdb_id=None, series_imdb_id=None, **kwargs):
+        super(Episode, self).__init__(name, **kwargs)
+
+        #: Series of the episode
+        self.series = series
+
+        #: Season number of the episode
+        self.season = season
+
+        #: Episode number of the episode
+        self.episode = episode
+
+        #: Title of the episode
+        self.title = title
+
+        #: Year of series
+        self.year = year
+
+        #: The series is the first with this name
+        self.original_series = original_series
+
+        #: TVDB id of the episode
+        self.tvdb_id = tvdb_id
+
+        #: TVDB id of the series
+        self.series_tvdb_id = series_tvdb_id
+
+        #: IMDb id of the series
+        self.series_imdb_id = series_imdb_id
+
+    @classmethod
+    def fromguess(cls, name, guess):
+        if guess['type'] != 'episode':
+            raise ValueError('The guess must be an episode guess')
+
+        if 'title' not in guess or 'episode' not in guess:
+            raise ValueError('Insufficient data to process the guess')
+
+        return cls(name, guess['title'], guess.get('season', 1), guess['episode'], title=guess.get('episode_title'),
+                   year=guess.get('year'), format=guess.get('format'), original_series='year' not in guess,
+                   release_group=guess.get('release_group'), resolution=guess.get('screen_size'),
+                   video_codec=guess.get('video_codec'), audio_codec=guess.get('audio_codec'))
+
+    @classmethod
+    def fromname(cls, name):
+        return cls.fromguess(name, guessit(name, {'type': 'episode'}))
+
+    def __repr__(self):
+        if self.year is None:
+            return '<%s [%r, %dx%d]>' % (self.__class__.__name__, self.series, self.season, self.episode)
+
+        return '<%s [%r, %d, %dx%d]>' % (self.__class__.__name__, self.series, self.year, self.season, self.episode)
+
+
+class Movie(Video):
+    """Movie :class:`Video`.
+
+    :param str title: title of the movie.
+    :param int year: year of the movie.
+    :param \*\*kwargs: additional parameters for the :class:`Video` constructor.
+
+    """
+    def __init__(self, name, title, year=None, **kwargs):
+        super(Movie, self).__init__(name, **kwargs)
+
+        #: Title of the movie
+        self.title = title
+
+        #: Year of the movie
+        self.year = year
+
+    @classmethod
+    def fromguess(cls, name, guess):
+        if guess['type'] != 'movie':
+            raise ValueError('The guess must be a movie guess')
+
+        if 'title' not in guess:
+            raise ValueError('Insufficient data to process the guess')
+
+        return cls(name, guess['title'], format=guess.get('format'), release_group=guess.get('release_group'),
+                   resolution=guess.get('screen_size'), video_codec=guess.get('video_codec'),
+                   audio_codec=guess.get('audio_codec'), year=guess.get('year'))
+
+    @classmethod
+    def fromname(cls, name):
+        return cls.fromguess(name, guessit(name, {'type': 'movie'}))
+
+    def __repr__(self):
+        if self.year is None:
+            return '<%s [%r]>' % (self.__class__.__name__, self.title)
+
+        return '<%s [%r, %d]>' % (self.__class__.__name__, self.title, self.year)

subliminal/videos.py

@@ -1,284 +0,0 @@
-# -*- coding: utf-8 -*-
-# Copyright 2011-2012 Antoine Bertin <diaoulael@gmail.com>
-#
-# This file is part of subliminal.
-#
-# subliminal is free software; you can redistribute it and/or modify it under
-# the terms of the GNU Lesser General Public License as published by
-# the Free Software Foundation; either version 3 of the License, or
-# (at your option) any later version.
-#
-# subliminal is distributed in the hope that it will be useful,
-# but WITHOUT ANY WARRANTY; without even the implied warranty of
-# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
-# GNU Lesser General Public License for more details.
-#
-# You should have received a copy of the GNU Lesser General Public License
-# along with subliminal.  If not, see <http://www.gnu.org/licenses/>.
-from . import subtitles
-from .language import Language
-from .utils import to_unicode
-import enzyme
-import guessit
-import hashlib
-import logging
-import mimetypes
-import os
-import struct
-
-
-__all__ = ['EXTENSIONS', 'MIMETYPES', 'Video', 'Episode', 'Movie', 'UnknownVideo',
-           'scan', 'hash_opensubtitles', 'hash_thesubdb']
-logger = logging.getLogger(__name__)
-
-#: Video extensions
-EXTENSIONS = ['.avi', '.mkv', '.mpg', '.mp4', '.m4v', '.mov', '.ogm', '.ogv', '.wmv',
-              '.divx', '.asf']
-
-#: Video mimetypes
-MIMETYPES = ['video/mpeg', 'video/mp4', 'video/quicktime', 'video/x-ms-wmv', 'video/x-msvideo',
-             'video/x-flv', 'video/x-matroska', 'video/x-matroska-3d']
-
-
-class Video(object):
-    """Base class for videos
-
-    :param string path: path
-    :param guess: guessed informations
-    :type guess: :class:`~guessit.guess.Guess`
-    :param string imdbid: imdbid
-
-    """
-    def __init__(self, path, guess, imdbid=None):
-        self.release = path
-        self.guess = guess
-        self.imdbid = imdbid
-        self._path = None
-        self.hashes = {}
-        if os.path.exists(path):
-            self._path = path
-            self.size = os.path.getsize(self._path)
-            self._compute_hashes()
-
-    @classmethod
-    def from_path(cls, path):
-        """Create a :class:`Video` subclass guessing all informations from the given path
-
-        :param string path: path
-        :return: video object
-        :rtype: :class:`Episode` or :class:`Movie` or :class:`UnknownVideo`
-
-        """
-        guess = guessit.guess_file_info(path, 'autodetect')
-        result = None
-        if guess['type'] == 'episode' and 'series' in guess and 'season' in guess and 'episodeNumber' in guess:
-            title = None
-            if 'title' in guess:
-                title = guess['title']
-            result = Episode(path, guess['series'], guess['season'], guess['episodeNumber'], title, guess)
-        if guess['type'] == 'movie' and 'title' in guess:
-            year = None
-            if 'year' in guess:
-                year = guess['year']
-            result = Movie(path, guess['title'], year, guess)
-        if not result:
-            result = UnknownVideo(path, guess)
-        if not isinstance(result, cls):
-            raise ValueError('Video is not of requested type')
-        return result
-
-    @property
-    def exists(self):
-        """Whether the video exists or not"""
-        if self._path:
-            return os.path.exists(self._path)
-        return False
-
-    @property
-    def path(self):
-        """Path to the video"""
-        return self._path
-
-    @path.setter
-    def path(self, value):
-        if not os.path.exists(value):
-            raise ValueError('Path does not exists')
-        self._path = value
-        self.size = os.path.getsize(self._path)
-        self._compute_hashes()
-
-    def _compute_hashes(self):
-        """Compute different hashes"""
-        self.hashes['OpenSubtitles'] = hash_opensubtitles(self.path)
-        self.hashes['TheSubDB'] = hash_thesubdb(self.path)
-
-    def scan(self):
-        """Scan and return associated subtitles
-
-        :return: associated subtitles
-        :rtype: list of :class:`~subliminal.subtitles.Subtitle`
-
-        """
-        if not self.exists:
-            return []
-        basepath = os.path.splitext(self.path)[0]
-        results = []
-        video_infos = None
-        try:
-            video_infos = enzyme.parse(self.path)
-            logger.debug(u'Succeeded parsing %s with enzyme: %r' % (self.path, video_infos))
-        except:
-            logger.debug(u'Failed parsing %s with enzyme' % self.path)
-        if isinstance(video_infos, enzyme.core.AVContainer):
-            results.extend([subtitles.EmbeddedSubtitle.from_enzyme(self.path, s) for s in video_infos.subtitles])
-        # cannot use glob here because it chokes if there are any square
-        # brackets inside the filename, so we have to use basic string
-        # startswith/endswith comparisons
-        folder, basename = os.path.split(basepath)
-        existing = [f for f in os.listdir(folder) if f.startswith(basename)]
-        for path in existing:
-            for ext in subtitles.EXTENSIONS:
-                if path.endswith(ext):
-                    language = Language(path[len(basename) + 1:-len(ext)], strict=False)
-                    results.append(subtitles.ExternalSubtitle(path, language))
-        return results
-
-    def __unicode__(self):
-        return to_unicode(self.path or self.release)
-
-    def __str__(self):
-        return unicode(self).encode('utf-8')
-
-    def __repr__(self):
-        return '%s(%s)' % (self.__class__.__name__, self)
-
-    def __hash__(self):
-        return hash(self.path or self.release)
-
-
-class Episode(Video):
-    """Episode :class:`Video`
-
-    :param string path: path
-    :param string series: series
-    :param int season: season number
-    :param int episode: episode number
-    :param string title: title
-    :param guess: guessed informations
-    :type guess: :class:`~guessit.guess.Guess`
-    :param string tvdbid: tvdbid
-    :param string imdbid: imdbid
-
-    """
-    def __init__(self, path, series, season, episode, title=None, guess=None, tvdbid=None, imdbid=None):
-        super(Episode, self).__init__(path, guess, imdbid)
-        self.series = series
-        self.title = title
-        self.season = season
-        self.episode = episode
-        self.tvdbid = tvdbid
-
-
-class Movie(Video):
-    """Movie :class:`Video`
-
-    :param string path: path
-    :param string title: title
-    :param int year: year
-    :param guess: guessed informations
-    :type guess: :class:`~guessit.guess.Guess`
-    :param string imdbid: imdbid
-
-    """
-    def __init__(self, path, title, year=None, guess=None, imdbid=None):
-        super(Movie, self).__init__(path, guess, imdbid)
-        self.title = title
-        self.year = year
-
-
-class UnknownVideo(Video):
-    """Unknown video"""
-    pass
-
-
-def scan(entry, max_depth=3, scan_filter=None, depth=0):
-    """Scan a path for videos and subtitles
-
-    :param string entry: path
-    :param int max_depth: maximum folder depth
-    :param function scan_filter: filter function that takes a path as argument and returns a boolean indicating whether it has to be filtered out (``True``) or not (``False``)
-    :param int depth: starting depth
-    :return: found videos and subtitles
-    :rtype: list of (:class:`Video`, [:class:`~subliminal.subtitles.Subtitle`])
-
-    """
-    if depth > max_depth and max_depth != 0:  # we do not want to search the whole file system except if max_depth = 0
-        return []
-    if os.path.isdir(entry):  # a dir? recurse
-        logger.debug(u'Scanning directory %s with depth %d/%d' % (entry, depth, max_depth))
-        result = []
-        for e in os.listdir(entry):
-            result.extend(scan(os.path.join(entry, e), max_depth, scan_filter, depth + 1))
-        return result
-    if os.path.isfile(entry) or depth == 0:
-        logger.debug(u'Scanning file %s with depth %d/%d' % (entry, depth, max_depth))
-        if depth != 0:  # trust the user: only check for valid format if recursing
-            if mimetypes.guess_type(entry)[0] not in MIMETYPES and os.path.splitext(entry)[1] not in EXTENSIONS:
-                return []
-            if scan_filter is not None and scan_filter(entry):
-                return []
-        video = Video.from_path(entry)
-        return [(video, video.scan())]
-    logger.warning(u'Scanning entry %s failed with depth %d/%d' % (entry, depth, max_depth))
-    return []  # anything else
-
-
-def hash_opensubtitles(path):
-    """Compute a hash using OpenSubtitles' algorithm
-
-    :param string path: path
-    :return: hash
-    :rtype: string
-
-    """
-    longlongformat = 'q'  # long long
-    bytesize = struct.calcsize(longlongformat)
-    with open(path, 'rb') as f:
-        filesize = os.path.getsize(path)
-        filehash = filesize
-        if filesize < 65536 * 2:
-            return None
-        for _ in range(65536 / bytesize):
-            filebuffer = f.read(bytesize)
-            (l_value,) = struct.unpack(longlongformat, filebuffer)
-            filehash += l_value
-            filehash = filehash & 0xFFFFFFFFFFFFFFFF  # to remain as 64bit number
-        f.seek(max(0, filesize - 65536), 0)
-        for _ in range(65536 / bytesize):
-            filebuffer = f.read(bytesize)
-            (l_value,) = struct.unpack(longlongformat, filebuffer)
-            filehash += l_value
-            filehash = filehash & 0xFFFFFFFFFFFFFFFF
-    returnedhash = '%016x' % filehash
-    logger.debug(u'Computed OpenSubtitle hash %s for %s' % (returnedhash, path))
-    return returnedhash
-
-
-def hash_thesubdb(path):
-    """Compute a hash using TheSubDB's algorithm
-
-    :param string path: path
-    :return: hash
-    :rtype: string
-
-    """
-    readsize = 64 * 1024
-    if os.path.getsize(path) < readsize:
-        return None
-    with open(path, 'rb') as f:
-        data = f.read(readsize)
-        f.seek(-readsize, os.SEEK_END)
-        data += f.read(readsize)
-    returnedhash = hashlib.md5(data).hexdigest()
-    logger.debug(u'Computed TheSubDB hash %s for %s' % (returnedhash, path))
-    return returnedhash

tests/__init__.py

@@ -1,26 +0,0 @@
-# -*- coding: utf-8 -*-
-# Copyright 2011-2012 Antoine Bertin <diaoulael@gmail.com>
-#
-# This file is part of subliminal.
-#
-# subliminal is free software; you can redistribute it and/or modify it under
-# the terms of the GNU Lesser General Public License as published by
-# the Free Software Foundation; either version 3 of the License, or
-# (at your option) any later version.
-#
-# subliminal is distributed in the hope that it will be useful,
-# but WITHOUT ANY WARRANTY; without even the implied warranty of
-# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
-# GNU Lesser General Public License for more details.
-#
-# You should have received a copy of the GNU Lesser General Public License
-# along with subliminal.  If not, see <http://www.gnu.org/licenses/>.
-from . import test_language, test_services, test_subliminal, test_videos
-import unittest
-
-
-suite = unittest.TestSuite([test_language.suite(), test_services.suite(), test_subliminal.suite(), test_videos.suite()])
-
-
-if __name__ == '__main__':
-    unittest.TextTestRunner().run(suite)