Repository: boto/botocore
Pull request #672 (2015-10-02 01:26:30)

Fix circular reference in docs
Removed dependency of session from docs package

For example, you no longer get a circular reference from doing this:
```py
from botocore.client import Config
```

cc @jamesls @mtdowling @rayluo @JordonPhillips 


Patch:
diff --git a/botocore/docs/__init__.py b/botocore/docs/__init__.py
index fe0e38848..b76f7990e 100644
--- a/botocore/docs/__init__.py
+++ b/botocore/docs/__init__.py
@@ -12,11 +12,10 @@
 # language governing permissions and limitations under the License.
 import os
 
-import botocore.session
 from botocore.docs.service import ServiceDocumenter
 
 
-def generate_docs(root_dir):
+def generate_docs(root_dir, session):
     """Generates the reference documentation for botocore
 
     This will go through every available AWS service and output ReSTructured
@@ -31,9 +30,8 @@ def generate_docs(root_dir):
         os.makedirs(services_doc_path)
 
     # Generate reference docs and write them out.
-    session = botocore.session.get_session()
     for service_name in session.get_available_services():
-        docs = ServiceDocumenter(service_name).document_service()
+        docs = ServiceDocumenter(service_name, session).document_service()
         service_doc_path = os.path.join(
             services_doc_path, service_name + '.rst')
         with open(service_doc_path, 'wb') as f:
diff --git a/botocore/docs/service.py b/botocore/docs/service.py
index 34371272c..36771b2d1 100644
--- a/botocore/docs/service.py
+++ b/botocore/docs/service.py
@@ -10,7 +10,6 @@
 # distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF
 # ANY KIND, either express or implied. See the License for the specific
 # language governing permissions and limitations under the License.
-import botocore.session
 from botocore.exceptions import DataNotFoundError
 from botocore.docs.utils import get_official_service_name
 from botocore.docs.client import ClientDocumenter
@@ -20,8 +19,8 @@ from botocore.docs.bcdoc.restdoc import DocumentStructure
 
 
 class ServiceDocumenter(object):
-    def __init__(self, service_name):
-        self._session = botocore.session.get_session()
+    def __init__(self, service_name, session):
+        self._session = session
         self._service_name = service_name
 
         self._client = self._session.create_client(
diff --git a/docs/source/conf.py b/docs/source/conf.py
index 4d35c3960..507eb115d 100644
--- a/docs/source/conf.py
+++ b/docs/source/conf.py
@@ -12,9 +12,10 @@
 # serve to show the default.
 
 import sys, os
+from botocore.session import get_session
 from botocore.docs import generate_docs
 
-generate_docs(os.path.dirname(os.path.abspath(__file__)))
+generate_docs(os.path.dirname(os.path.abspath(__file__)), get_session())
 
 # 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


Test patch:
diff --git a/tests/functional/docs/__init__.py b/tests/functional/docs/__init__.py
index 242b47914..fd55e7208 100644
--- a/tests/functional/docs/__init__.py
+++ b/tests/functional/docs/__init__.py
@@ -11,10 +11,14 @@
 # ANY KIND, either express or implied. See the License for the specific
 # language governing permissions and limitations under the License.
 from tests import unittest
+from botocore.session import get_session
 from botocore.docs.service import ServiceDocumenter
 
 
 class BaseDocsFunctionalTest(unittest.TestCase):
+    def setUp(self):
+        self._session = get_session()
+
     def assert_contains_line(self, line, contents):
         contents = contents.decode('utf-8')
         self.assertIn(line, contents)
@@ -58,7 +62,8 @@ class BaseDocsFunctionalTest(unittest.TestCase):
 
     def get_parameter_documentation_from_service(
             self, service_name, method_name, param_name):
-        contents = ServiceDocumenter(service_name).document_service()
+        contents = ServiceDocumenter(
+            service_name, self._session).document_service()
         method_contents = self.get_method_document_block(
             method_name, contents)
         return self.get_parameter_document_block(
@@ -66,7 +71,8 @@ class BaseDocsFunctionalTest(unittest.TestCase):
 
     def assert_is_documented_as_autopopulated_param(
             self, service_name, method_name, param_name, doc_string=None):
-        contents = ServiceDocumenter(service_name).document_service()
+        contents = ServiceDocumenter(
+            service_name, self._session).document_service()
         # Pick an arbitrary method that uses AccountId.
         method_contents = self.get_method_document_block(
             method_name, contents)
diff --git a/tests/functional/docs/test_s3.py b/tests/functional/docs/test_s3.py
index 6ad92405f..cbf06c8a6 100644
--- a/tests/functional/docs/test_s3.py
+++ b/tests/functional/docs/test_s3.py
@@ -29,7 +29,8 @@ class TestS3Docs(BaseDocsFunctionalTest):
                             'put_bucket_replication', 'put_bucket_website',
                             'put_bucket_request_payment', 'put_object_acl',
                             'put_bucket_versioning']
-        service_contents = ServiceDocumenter('s3').document_service()
+        service_contents = ServiceDocumenter(
+            's3', self._session).document_service()
         for method_name in modified_methods:
             method_contents = self.get_method_document_block(
                 method_name, service_contents)
diff --git a/tests/unit/docs/test_docs.py b/tests/unit/docs/test_docs.py
index f240dd5b4..e191e05cc 100644
--- a/tests/unit/docs/test_docs.py
+++ b/tests/unit/docs/test_docs.py
@@ -17,6 +17,7 @@ import tempfile
 import mock
 
 from tests.unit.docs import BaseDocsTest
+from botocore.session import get_session
 from botocore.docs import generate_docs
 
 
@@ -39,8 +40,9 @@ class TestGenerateDocs(BaseDocsTest):
         self.available_service_patch.stop()
 
     def test_generate_docs(self):
+        session = get_session()
         # Have the rst files get written to the temporary directory
-        generate_docs(self.docs_root)
+        generate_docs(self.docs_root, session)
 
         reference_services_path = os.path.join(
             self.docs_root, 'reference', 'services')
diff --git a/tests/unit/docs/test_service.py b/tests/unit/docs/test_service.py
index 51451f601..596c6d9e1 100644
--- a/tests/unit/docs/test_service.py
+++ b/tests/unit/docs/test_service.py
@@ -15,6 +15,7 @@ import os
 import mock
 
 from tests.unit.docs import BaseDocsTest
+from botocore.session import get_session
 from botocore.docs.service import ServiceDocumenter
 
 
@@ -25,7 +26,9 @@ class TestServiceDocumenter(BaseDocsTest):
         self.setup_client()
         with mock.patch('botocore.session.create_loader',
                         return_value=self.loader):
-            self.service_documenter = ServiceDocumenter('myservice')
+            session = get_session()
+            self.service_documenter = ServiceDocumenter(
+                'myservice', session)
 
     def test_document_service(self):
         # Note that not everything will be included as it is just