docs

CHANGES.rst

@@ -1,5 +1,5 @@
-Changelog
-=========
+Changes by Version
+==================
 
 
 0.16.0 (unreleased)
@@ -25,6 +25,8 @@ Changelog
 - **BREAKING** - Remove third ``proxy`` argument from the server handler
   interface.
 - **BREAKING** - ``ZipkinTraceHook`` is not longer registered by default.
+- **BREAKING** - ``tchannel.sync.client.TChannelSyncClient`` replaced with
+  ``tchannel.sync.TChannel``.
 
 
 0.15.2 (2015-08-07)

Makefile

@@ -14,7 +14,6 @@ TEST_LOG_FILE=test-server.log
 
 .DEFAULT_GOAL := test-lint
 
-.PHONY: install test test_ci test-lint testhtml clean lint release docs vcr-thrift gen_thrift
 
 env/bin/activate:
 	virtualenv env
@@ -23,45 +22,61 @@ env_install: env/bin/activate
 	./env/bin/pip install -r requirements-test.txt --download-cache $(HOME)/.cache/pip
 	./env/bin/python setup.py develop
 
+.PHONY: tox_install
 tox_install:
 	pip install -r requirements-test.txt --download-cache $(HOME)/.cache/pip
 	python setup.py develop
 
+.PHONY: install
 install:
 ifdef TOX_ENV
 	make tox_install
 else
 	make env_install
 endif
 
+.PHONY: test_server
 test_server:
 	# TODO: use ${TEST_LOG_FILE}
 	./env/bin/python examples/tchannel_server.py --host ${TEST_HOST} --port ${TEST_PORT}
 
+.PHONY: test
 test: clean
 	$(pytest) $(test_args)
 
+.PHONY: test_ci
 test_ci: clean
 	tox -e $(TOX_ENV) -- tests
 
+.PHONY: testhtml
 testhtml: clean
 	$(pytest) $(html_report) && open htmlcov/index.html
 
+.PHONY: clean
 clean:
 	rm -rf dist/
 	rm -rf build/
 	@find $(project) -name "*.pyc" -delete
 
+.PHONY: lint
 lint:
 	@$(flake8) $(project) tests examples
 
+.PHONY: test-lint
 test-lint: test lint
 
+.PHONY: docs
 docs:
 	make -C docs html
 
+.PHONY: docsopen
+docsopen: docs
+	open docs/_build/html/index.html
+
+.PHONY: vcr-thrift
 vcr-thrift:
 	make -C ./tchannel/testing/vcr all
 
+.PHONY: gen_thrift
 gen_thrift:
     thrift --gen py:new_style,slots,dynamic -out tests/data/generated tests/data/idls/ThriftTest.thrift

UPGRADE.rst

@@ -1,5 +1,5 @@
-Version Upgrade Guide
-=====================
+Upgrade Guide
+=============
 
 Migrating to a version of TChannel with breaking changes? This guide documents
 what broke and how to safely migrate to newer versions.
@@ -17,7 +17,7 @@ From 0.15 to 0.16
       from tchannel import TChannel
 
       @tchannel.register('endpoint', 'json')
-      def endpoint(request, response):
+      def endpoint(request, response, proxy):
           response.write({'resp': 'body'})
 
 
@@ -31,7 +31,58 @@ From 0.15 to 0.16
       def endpoint(request):
           return Response({'resp': 'body'})
 
-- `` from tchannel.tornado import TChannel`` is deprecated.
+- ``TChannelSyncClient`` has been replaced with ``tchannel.sync.TChannel``.
+  This new synchronous client has been significantly re-worked to more closely
+  match the asynchronous ``TChannel`` API. ``tchannel.sync.thrift.client_for``
+  has been removed and ``tchannel.thrift.client_for`` should be used instead.
+  This new API allows specifying headers, timeouts, and retry behavior with
+  Thrift requests.
+
+  Before:
+
+  .. code:: python
+
+      from tchannel.sync import TChannelSyncClient
+      from tchannel.sync.thrift import client_for
+
+      from generated.thrift.code import MyThriftService
+
+      tchannel_thrift_client = client_for('foo', MyThriftService)
+
+      tchannel = TChannelSyncClient(name='bar')
+
+      future = tchannel_thrift_client.someMethod(...)
+
+      result = future.result()
+
+
+  After:
+
+  .. code:: python
+
+      from tchannel import thrift_request_builder
+      from tchannel.sync import TChannel
+      from tchannel.retry import CONNECTION_ERROR_AND_TIMEOUT
+
+      from generated.thrift.code import MyThriftService
+
+      tchannel_thrift_client = thrift_request_builder(
+          service='foo',
+          thrift_module=MyThriftService,
+      )
+
+      tchannel = TChannel(name='bar')
+
+      future = tchannel.thrift(
+          tchannel_thrift_client.someMethod(...)
+          headers={'foo': 'bar'},
+          retry_on=CONNECTION_ERROR_AND_TIMEOUT,
+          timeout=1000,
+      )
+
+      result = future.result()
+
+- ``from tchannel.tornado import TChannel`` is deprecated.
 
 - Remove ``retry_delay`` option from ``tchannel.tornado.peer.PeerClientOperation.send``
   method.

docs/api.rst

@@ -6,40 +6,64 @@ TChannel
 --------
 
 .. autoclass:: tchannel.TChannel
+    :special-members: __init__
     :members:
 
 .. autoclass:: tchannel.Request
     :members:
 
 .. autoclass:: tchannel.Response
-
-.. autoclass:: tchannel.schemes.RawArgScheme
     :members:
 
-.. autoclass:: tchannel.schemes.JsonArgScheme
-    :members:
+
+Serialization Schemes
+---------------------
+
+Thrift
+~~~~~~
 
 .. autoclass:: tchannel.schemes.ThriftArgScheme
-    :members:
+    :members: __call__, register
 
 .. autofunction:: tchannel.thrift_request_builder
 
 
-Exceptions
-----------
+JSON
+~~~~
 
+.. autoclass:: tchannel.schemes.JsonArgScheme
+    :members: __call__, register
+
+Raw
+~~~
+.. autoclass:: tchannel.schemes.RawArgScheme
+    :members: __call__, register
+
+
+Exception Handling
+------------------
+
+Errors
+~~~~~~
 .. automodule:: tchannel.errors
     :members:
+    :show-inheritance:
 
+Retry Behavior
+~~~~~~~~~~~~~~
+
+These values can be passed as the ``retry_on`` behavior to
+:py:meth:`tchannel.TChannel.call`.
+
+.. automodule:: tchannel.retry
+    :members:
 
 
 Synchronous Client
 ------------------
 
-.. automodule:: tchannel.sync.client
-    :members:
-
-.. automodule:: tchannel.sync.thrift
+.. autoclass:: tchannel.sync.TChannel
+    :inherited-members:
     :members:
 
 
@@ -53,19 +77,3 @@ Testing
     the module documentation for it explicitly calls out members that should be
     documented.
 
-
-Deprecated
-----------
-
-.. autoclass:: tchannel.tornado.TChannel
-
-.. autoclass:: tchannel.tornado.Request
-    :members:
-
-.. autoclass:: tchannel.tornado.Response
-    :members:
-
-.. automodule:: tchannel.thrift.client
-    :members:
-
-

docs/changelog.rst

@@ -1 +1,6 @@
+=========
+Changelog
+=========
+
 .. include:: ../CHANGES.rst
+.. include:: ../UPGRADE.rst

docs/conf.py

@@ -46,7 +46,9 @@ def _warn_node(self, msg, node):
     'sphinx.ext.viewcode',
 ]
 
-# Add any paths that contain templates here, relative to this directory.
+autodoc_member_order = 'bysource'
+
+# Add any paths that contin templates here, relative to this directory.
 templates_path = ['_templates']
 
 # The suffix of source filenames.

tchannel/errors.py

@@ -21,19 +21,44 @@
 from __future__ import absolute_import
 
 
+#: The request timed out.
 TIMEOUT = 0x01
+
+#: The request was canceled.
 CANCELED = 0x02
+
+#: The server was busy.
 BUSY = 0x03
+
+# The server declined the request.
 DECLINED = 0x04
+
+# The server's handler raised an unexpected exception.
 UNEXPECTED_ERROR = 0x05
+
+#: The request was bad.
 BAD_REQUEST = 0x06
+
+#: There was a network error when sending the request.
 NETWORK_ERROR = 0x07
+
+#: The server handling the request is unhealthy.
 UNHEALTHY = 0x08
+
+#: There was a fatal protocol-level error.
 FATAL = 0xFF
 
 
 class TChannelError(Exception):
-    """Represent a TChannel-generated exception."""
+    """A TChannel-generated exception.
+
+    :ivar code:
+        The error code for this error. See the `Specification`_ for a
+        description of these codes.
+    :vartype code:
+
+    .. _`Specification`: http://tchannel.readthedocs.org/en/latest/protocol/#code1_1
+    """
 
     __slots__ = (
         'code',
@@ -57,6 +82,10 @@ def __init__(
 
     @classmethod
     def from_code(cls, code, **kw):
+        """Construct a ``TChannelError`` instance from an error code.
+
+        This will return the appropriate class type for the given code.
+        """
         return {
             TIMEOUT: TimeoutError,
             CANCELED: CanceledError,
@@ -71,15 +100,30 @@ def from_code(cls, code, **kw):
 
 
 class RetryableError(TChannelError):
-    pass
+    """An error where the original request is always safe to retry.
+
+    It is always safe to retry a request with this category of errors. The
+    original request was never handled.
+    """
 
 
 class MaybeRetryableError(TChannelError):
-    pass
+    """An error where the original request may be safe to retry.
+
+    The original request may have reached the intended service. Hence, the
+    request should only be retried if it is known to be `idempotent`_.
+
+    .. _`idempotent`:
+        https://en.wikipedia.org/wiki/Idempotence#Computer_science_meaning
+    """
 
 
 class NotRetryableError(TChannelError):
-    pass
+    """An error where the original request should not be re-sent.
+
+    Something was fundamentally wrong with the request and it should not be
+    retried.
+    """
 
 
 class TimeoutError(MaybeRetryableError):
@@ -134,12 +178,12 @@ class NoAvailablePeerError(RetryableError):
 
 
 class AlreadyListeningError(FatalProtocolError):
-    """Represents exception from attempting to listen multiple times."""
+    """Raised when attempting to listen multiple times."""
     pass
 
 
 class OneWayNotSupportedError(BadRequestError):
-    """Raised when oneway Thrift procedure is called."""
+    """Raised when a one-way Thrift procedure is called."""
     pass