From 07c43a91cfce96e91fe943ffd9fe5b9181932803 Mon Sep 17 00:00:00 2001
From: Konsta Vesterinen <konsta.vesterinen@gmail.com>
Date: Wed, 8 Apr 2015 22:03:59 +0300
Subject: [PATCH] Improve country docs

---
 docs/data_types.rst                    |  4 +++
 sqlalchemy_utils/primitives/country.py | 44 ++++++++++++++++++++++++++
 sqlalchemy_utils/types/country.py      |  4 +--
 3 files changed, 50 insertions(+), 2 deletions(-)

diff --git a/docs/data_types.rst b/docs/data_types.rst
index 3b6546f..e414cca 100644
--- a/docs/data_types.rst
+++ b/docs/data_types.rst
@@ -38,6 +38,10 @@ CountryType
 
 .. autoclass:: CountryType
 
+.. module:: sqlalchemy_utils.primitives.country
+
+.. autoclass:: Country
+
 
 CurrencyType
 ^^^^^^^^^^^^
diff --git a/sqlalchemy_utils/primitives/country.py b/sqlalchemy_utils/primitives/country.py
index c768169..95e47ec 100644
--- a/sqlalchemy_utils/primitives/country.py
+++ b/sqlalchemy_utils/primitives/country.py
@@ -5,6 +5,50 @@ from sqlalchemy_utils.utils import str_coercible
 
 @str_coercible
 class Country(object):
+    """
+    Country class wraps a 2 to 3 letter country code. It provides various
+    convenience properties and methods.
+
+    ::
+
+        from babel import Locale
+        from sqlalchemy_utils import Country, i18n
+
+
+        # First lets add a locale getter for testing purposes
+        i18n.get_locale = lambda: Locale('en')
+
+
+        Country('FI').name  # Finland
+        Country('FI').code  # FI
+
+        Country(Country('FI')).code  # 'FI'
+
+    Country always validates the given code.
+
+    ::
+
+        Country(None)  # raises TypeError
+
+        Country('UnknownCode')  # raises ValueError
+
+
+    Country supports equality operators.
+
+    ::
+
+        Country('FI') == Country('FI')
+        Country('FI') != Country('US')
+
+
+    Country objects are hashable.
+
+
+    ::
+
+        assert hash(Country('FI')) == hash('FI')
+
+    """
     def __init__(self, code_or_country):
         if isinstance(code_or_country, Country):
             self.code = code_or_country.code
diff --git a/sqlalchemy_utils/types/country.py b/sqlalchemy_utils/types/country.py
index 7f591d3..1b310a6 100644
--- a/sqlalchemy_utils/types/country.py
+++ b/sqlalchemy_utils/types/country.py
@@ -7,8 +7,8 @@ from .scalar_coercible import ScalarCoercible
 
 class CountryType(types.TypeDecorator, ScalarCoercible):
     """
-    Changes Country objects to a string representation on the way in and
-    changes them back to Country objects on the way out.
+    Changes :class:`.Country` objects to a string representation on the way in
+    and changes them back to :class:`.Country` objects on the way out.
 
     In order to use CountryType you need to install Babel_ first.