:mod:`humphrey.core.movie`
==========================

.. currentmodule:: humphrey.core.movie

.. automodule:: humphrey.core.movie

Every movie has a title which must be specified on initialization. The title may
not be empty and may not consist only of whitespace. Other information about a
movie includes its year, directors and cast.

It is possible -and recommended- to store the IMDb ids of movies. The IMDb id is
a 7-digit string and it will be used as the primary value to identify a movie.
Two movies are considered equal if they have the same IMDb id, regardless of
their other data::

  >>> m1 = Movie(u"The Matrix Reloaded", imdb_id=u'0234215')
  >>> m2 = Movie(u"The Matrix 2", imdb_id=u'0234215')
  >>> m1 == m2
  True

If they have no IMDb ids, their titles will be checked. A comparison between a
movie and a title is also valid::

  >>> m = Movie(u"The Matrix")
  >>> m == u"The Matrix"
  True

For every movie, there is also a sortable title which is used for comparing
titles. In sortable titles, articles like "The", "An" will not be considered.
This is also the default when comparing two movies::

  >>> m1 = Movie(u"The Matrix")
  >>> m2 = Movie(u"Suspiria")
  >>> m1 < m2
  True

If two movies have the same sortable title, the older movie comes first::

  >>> m1 = Movie(u"The Shining", year=1980)
  >>> m2 = Movie(u"The Shining", year=1997)
  >>> m1 < m2
  True

Other Titles
------------

Movies can have more than one title and they can have different titles in
different countries and languages. An :class:`AKA` (*also known as*) represents
another title for a movie.

An AKA must be initialized with a title text and can be checked for equality
against a title::

  >>> a = AKA(u"Deep Red")
  >>> a == u"Deep Red"
  True

When another title for a movie is obtained from IMDb, it is checked to see
whether it is for a country for which titles will be accepted. These countries
are kept in :attr:`Movie.AKA_COUNTRIES`. The following helper functions can be
used for getting the title and notes from an a.k.a. string as provided by IMDb:

.. function:: get_aka_info(unicode) -> unicode

   Return the title from an annotated a.k.a. string.

.. function:: get_aka_notes(unicode) -> unicode

   Return the notes from an annotated a.k.a. string.


API
---

.. autoclass:: Movie
   :members:

.. autoclass:: AKA
   :members: