update docs to document TCPStatsClient

3 files changed, 107 insertions, 0 deletions

diff --git a/docs/index.rst b/docs/index.rst
index b56bb64..ed4cb6c 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -70,6 +70,7 @@ Contents
    types.rst
    timing.rst
    pipeline.rst
+   tcp.rst
    reference.rst
    contributing.rst
 
diff --git a/docs/reference.rst b/docs/reference.rst
index 0c0202e..e4527a7 100644
--- a/docs/reference.rst
+++ b/docs/reference.rst
@@ -275,6 +275,93 @@ stats.
    This method is not implemented on the base StatsClient class.
 
 
+.. _TCPStatsClient:
+
+``TCPStatsClient``
+==================
+
+::
+
+    TCPStatsClient(host='localhost', port=8125, prefix=None, timeout=None)
+
+Create a new ``TCPStatsClient`` instance with the appropriate connection
+and prefix information.
+
+* ``host``: the hostname or IPv4 address of the statsd_ server.
+
+* ``port``: the port of the statsd server.
+
+* ``prefix``: a prefix to distinguish and group stats from an
+  application or environment.
+
+* ``timeout``: socket timeout for any actions on the connection socket.
+
+
+``TCPStatsClient`` implements all methods of ``StatsClient``, with the
+difference that it is not thread safe and it can raise exceptions on
+connection errors.  On the contrary to ``StatsClient`` it uses a ``TCP``
+connection to connect to Statsd.
+Additionally to the methods of ``StatsClient`` it has a few which are
+specific to ``TCP`` connections.
+
+
+.. _tcp_close:
+
+``close``
+---------
+
+::
+
+    from statsd import TCPStatsClient
+
+    statsd = TCPStatsClient()
+    statsd.incr('some.event')
+    statsd.close()
+
+Closes a connection that's currently open and deletes it's socket. If this is
+called on a ``TCPStatsClient`` which currently has no open connection it is a
+non-action.
+
+
+.. _tcp_connect:
+
+``connect``
+-----------
+
+::
+
+    from statsd import TCPStatsClient
+
+    statsd = TCPStatsClient()
+    statsd.incr('some.event')  # calls connect() internally
+    statsd.close()
+    statsd.connect()  # creates new connection
+
+Creates a connection to Statsd. If there are errors like connection timed out
+or connection refused, the according exceptions will be raised. It is usually
+not necessary to call this method because sending data to Statsd will call
+``connect`` implicitely if the current instance of ``TCPStatsClient`` does not
+already hold an open connection.
+
+
+.. _tcp_reconnect:
+
+``reconnect``
+-------------
+
+::
+
+    from statsd import TCPStatsClient
+
+    statsd = TCPStatsClient()
+    statsd.incr('some.event')
+    statsd.reconnect()  # closes open connection and creates new one
+
+Closes a currently existing connection and replaces it with a new one. If no
+connection exists already it will simply create a new one.  Internally this
+does nothing else than calling ``close()`` and ``connect()``.
+
+
 .. _statsd: https://github.com/etsy/statsd
 .. _0ed78be: https://github.com/etsy/statsd/commit/0ed78be7
 .. _1c10cfc0ac: https://github.com/etsy/statsd/commit/1c10cfc0ac
diff --git a/docs/tcp.rst b/docs/tcp.rst
new file mode 100644
index 0000000..3c81af6
--- /dev/null
+++ b/docs/tcp.rst
@@ -0,0 +1,19 @@
+.. _tcp-chapter:
+
+==============
+TCPStatsClient
+==============
+
+The ``TCPStatsClient`` class has a very similar interface to ``StatsClient``,
+but internally it uses ``TCP`` connections instead of ``UDP``. These are the
+main differencies when using ``TCPStatsClient`` compared to ``StatsClient``:
+
+* The constructor supports a ``timeout`` parameter to set a timeout on all
+  socket actions.
+
+* The methods ``connect`` and all methods that send data can potentially raise
+  socket exceptions.
+
+* It is not thread-safe, so it is recommended to not share it across threads
+  unless a lot of attention is paid to make sure that no two threads ever use
+  it at once.