summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
Diffstat
-rw-r--r--README.md40
-rw-r--r--README.rst53
-rw-r--r--docs/api_reference.rst64
-rw-r--r--docs/apidoc/kafka.consumer.rst46
-rw-r--r--docs/apidoc/kafka.partitioner.rst38
-rw-r--r--docs/apidoc/kafka.producer.rst38
-rw-r--r--docs/apidoc/kafka.rst79
-rw-r--r--docs/apidoc/modules.rst7
-rw-r--r--docs/conf.py10
-rw-r--r--docs/index.rst5
-rw-r--r--docs/usage.rst8
-rw-r--r--kafka/consumer/kafka.py7
-rw-r--r--setup.py18
-rw-r--r--tox.ini13
14 files changed, 303 insertions, 123 deletions
diff --git a/README.md b/README.md
deleted file mode 100644
index 031382c..0000000
--- a/README.md
+++ /dev/null
@@ -1,40 +0,0 @@
-# Kafka Python client
-
-[![Build Status](https://api.travis-ci.org/mumrah/kafka-python.png?branch=master)](https://travis-ci.org/mumrah/kafka-python)
-[![Coverage Status](https://coveralls.io/repos/mumrah/kafka-python/badge.svg?branch=master)](https://coveralls.io/r/mumrah/kafka-python?branch=master)
-[![Full documentation available on ReadTheDocs](https://readthedocs.org/projects/kafka-python/badge/?version=latest)](https://readthedocs.org/projects/kafka-python/?badge=latest)
-
-[Full documentation available on ReadTheDocs](http://kafka-python.readthedocs.org/en/latest/)
-
-This module provides low-level protocol support for Apache Kafka as well as
-high-level consumer and producer classes. Request batching is supported by the
-protocol as well as broker-aware request routing. Gzip and Snappy compression
-is also supported for message sets.
-
-http://kafka.apache.org/
-
-On Freenode IRC at #kafka-python, as well as #apache-kafka
-
-For general discussion of kafka-client design and implementation (not python specific),
-see https://groups.google.com/forum/m/#!forum/kafka-clients
-
-# License
-
-Copyright 2015, David Arthur under Apache License, v2.0. See `LICENSE`
-
-# Status
-
-The current stable version of this package is [**0.9.3**](https://github.com/mumrah/kafka-python/releases/tag/v0.9.3) and is compatible with
-
-Kafka broker versions
-- 0.8.2.0 [offset management currently ZK only -- does not support ConsumerCoordinator offset management APIs]
-- 0.8.1.1
-- 0.8.1
-- 0.8.0
-
-Python versions
-- 2.6 (tested on 2.6.9)
-- 2.7 (tested on 2.7.9)
-- 3.3 (tested on 3.3.5)
-- 3.4 (tested on 3.4.2)
-- pypy (tested on pypy 2.4.0 / python 2.7.8)
diff --git a/README.rst b/README.rst
new file mode 100644
index 0000000..5405f92
--- /dev/null
+++ b/README.rst
@@ -0,0 +1,53 @@
+Kafka Python client
+------------------------
+.. image:: https://api.travis-ci.org/mumrah/kafka-python.png?branch=master
+ :target: https://travis-ci.org/mumrah/kafka-python
+ :alt: Build Status
+
+.. image:: https://coveralls.io/repos/mumrah/kafka-python/badge.svg?branch=master
+ :target: https://coveralls.io/r/mumrah/kafka-python?branch=master
+ :alt: Coverage Status
+
+.. image:: https://readthedocs.org/projects/kafka-python/badge/?version=latest
+ :target: http://kafka-python.readthedocs.org/en/latest/
+ :alt: Full documentation available on ReadTheDocs
+
+`Full documentation available on ReadTheDocs`_
+
+This module provides low-level protocol support for Apache Kafka as well as
+high-level consumer and producer classes. Request batching is supported by the
+protocol as well as broker-aware request routing. Gzip and Snappy compression
+is also supported for message sets.
+
+http://kafka.apache.org/
+
+On Freenode IRC at #kafka-python, as well as #apache-kafka
+
+For general discussion of kafka-client design and implementation (not python specific),
+see https://groups.google.com/forum/#!forum/kafka-clients
+
+License
+----------
+Copyright 2015, David Arthur under Apache License, v2.0. See `LICENSE`
+
+Status
+----------
+The current stable version of this package is `0.9.3`_ and is compatible with:
+
+Kafka broker versions
+
+- 0.8.2.0 [offset management currently ZK only -- does not support ConsumerCoordinator offset management APIs]
+- 0.8.1.1
+- 0.8.1
+- 0.8.0
+
+Python versions
+
+- 2.6 (tested on 2.6.9)
+- 2.7 (tested on 2.7.9)
+- 3.3 (tested on 3.3.5)
+- 3.4 (tested on 3.4.2)
+- pypy (tested on pypy 2.4.0 / python 2.7.8)
+
+.. _Full documentation available on ReadTheDocs: http://kafka-python.readthedocs.org/en/latest/
+.. _0.9.3: https://github.com/mumrah/kafka-python/releases/tag/v0.9.3
diff --git a/docs/api_reference.rst b/docs/api_reference.rst
deleted file mode 100644
index 8804664..0000000
--- a/docs/api_reference.rst
+++ /dev/null
@@ -1,64 +0,0 @@
-API Reference
-=============
-
-kafka
------
-.. automodule:: kafka.client
- :members:
-
-.. automodule:: kafka.codec
- :members:
-
-.. automodule:: kafka.common
- :members:
-
-.. automodule:: kafka.conn
- :members:
-
-.. automodule:: kafka.context
- :members:
-
-.. automodule:: kafka.protocol
- :members:
-
-.. automodule:: kafka.util
- :members:
-
-
-kafka.consumer
---------------
-.. automodule:: kafka.consumer.base
- :members:
-
-.. automodule:: kafka.consumer.kafka
- :members:
-
-.. automodule:: kafka.consumer.multiprocess
- :members:
-
-.. automodule:: kafka.consumer.simple
- :members:
-
-
-kafka.partitioner
------------------
-.. automodule:: kafka.partitioner.base
- :members:
-
-.. automodule:: kafka.partitioner.hashed
- :members:
-
-.. automodule:: kafka.partitioner.roundrobin
- :members:
-
-
-kafka.producer
---------------
-.. automodule:: kafka.producer.base
- :members:
-
-.. automodule:: kafka.producer.keyed
- :members:
-
-.. automodule:: kafka.producer.simple
- :members:
diff --git a/docs/apidoc/kafka.consumer.rst b/docs/apidoc/kafka.consumer.rst
new file mode 100644
index 0000000..8595f99
--- /dev/null
+++ b/docs/apidoc/kafka.consumer.rst
@@ -0,0 +1,46 @@
+kafka.consumer package
+======================
+
+Submodules
+----------
+
+kafka.consumer.base module
+--------------------------
+
+.. automodule:: kafka.consumer.base
+ :members:
+ :undoc-members:
+ :show-inheritance:
+
+kafka.consumer.kafka module
+---------------------------
+
+.. automodule:: kafka.consumer.kafka
+ :members:
+ :undoc-members:
+ :show-inheritance:
+
+kafka.consumer.multiprocess module
+----------------------------------
+
+.. automodule:: kafka.consumer.multiprocess
+ :members:
+ :undoc-members:
+ :show-inheritance:
+
+kafka.consumer.simple module
+----------------------------
+
+.. automodule:: kafka.consumer.simple
+ :members:
+ :undoc-members:
+ :show-inheritance:
+
+
+Module contents
+---------------
+
+.. automodule:: kafka.consumer
+ :members:
+ :undoc-members:
+ :show-inheritance:
diff --git a/docs/apidoc/kafka.partitioner.rst b/docs/apidoc/kafka.partitioner.rst
new file mode 100644
index 0000000..ea215f1
--- /dev/null
+++ b/docs/apidoc/kafka.partitioner.rst
@@ -0,0 +1,38 @@
+kafka.partitioner package
+=========================
+
+Submodules
+----------
+
+kafka.partitioner.base module
+-----------------------------
+
+.. automodule:: kafka.partitioner.base
+ :members:
+ :undoc-members:
+ :show-inheritance:
+
+kafka.partitioner.hashed module
+-------------------------------
+
+.. automodule:: kafka.partitioner.hashed
+ :members:
+ :undoc-members:
+ :show-inheritance:
+
+kafka.partitioner.roundrobin module
+-----------------------------------
+
+.. automodule:: kafka.partitioner.roundrobin
+ :members:
+ :undoc-members:
+ :show-inheritance:
+
+
+Module contents
+---------------
+
+.. automodule:: kafka.partitioner
+ :members:
+ :undoc-members:
+ :show-inheritance:
diff --git a/docs/apidoc/kafka.producer.rst b/docs/apidoc/kafka.producer.rst
new file mode 100644
index 0000000..bd850bb
--- /dev/null
+++ b/docs/apidoc/kafka.producer.rst
@@ -0,0 +1,38 @@
+kafka.producer package
+======================
+
+Submodules
+----------
+
+kafka.producer.base module
+--------------------------
+
+.. automodule:: kafka.producer.base
+ :members:
+ :undoc-members:
+ :show-inheritance:
+
+kafka.producer.keyed module
+---------------------------
+
+.. automodule:: kafka.producer.keyed
+ :members:
+ :undoc-members:
+ :show-inheritance:
+
+kafka.producer.simple module
+----------------------------
+
+.. automodule:: kafka.producer.simple
+ :members:
+ :undoc-members:
+ :show-inheritance:
+
+
+Module contents
+---------------
+
+.. automodule:: kafka.producer
+ :members:
+ :undoc-members:
+ :show-inheritance:
diff --git a/docs/apidoc/kafka.rst b/docs/apidoc/kafka.rst
new file mode 100644
index 0000000..eb04c35
--- /dev/null
+++ b/docs/apidoc/kafka.rst
@@ -0,0 +1,79 @@
+kafka package
+=============
+
+Subpackages
+-----------
+
+.. toctree::
+
+ kafka.consumer
+ kafka.partitioner
+ kafka.producer
+
+Submodules
+----------
+
+kafka.client module
+-------------------
+
+.. automodule:: kafka.client
+ :members:
+ :undoc-members:
+ :show-inheritance:
+
+kafka.codec module
+------------------
+
+.. automodule:: kafka.codec
+ :members:
+ :undoc-members:
+ :show-inheritance:
+
+kafka.common module
+-------------------
+
+.. automodule:: kafka.common
+ :members:
+ :undoc-members:
+ :show-inheritance:
+
+kafka.conn module
+-----------------
+
+.. automodule:: kafka.conn
+ :members:
+ :undoc-members:
+ :show-inheritance:
+
+kafka.context module
+--------------------
+
+.. automodule:: kafka.context
+ :members:
+ :undoc-members:
+ :show-inheritance:
+
+kafka.protocol module
+---------------------
+
+.. automodule:: kafka.protocol
+ :members:
+ :undoc-members:
+ :show-inheritance:
+
+kafka.util module
+-----------------
+
+.. automodule:: kafka.util
+ :members:
+ :undoc-members:
+ :show-inheritance:
+
+
+Module contents
+---------------
+
+.. automodule:: kafka
+ :members:
+ :undoc-members:
+ :show-inheritance:
diff --git a/docs/apidoc/modules.rst b/docs/apidoc/modules.rst
new file mode 100644
index 0000000..db3e580
--- /dev/null
+++ b/docs/apidoc/modules.rst
@@ -0,0 +1,7 @@
+kafka
+=====
+
+.. toctree::
+ :maxdepth: 4
+
+ kafka
diff --git a/docs/conf.py b/docs/conf.py
index 9e95f79..ea223c2 100644
--- a/docs/conf.py
+++ b/docs/conf.py
@@ -30,6 +30,7 @@ import os
# ones.
extensions = [
'sphinx.ext.autodoc',
+ 'sphinx.ext.intersphinx',
'sphinx.ext.viewcode',
'sphinxcontrib.napoleon',
]
@@ -57,7 +58,7 @@ copyright = u'2015, David Arthur'
# The short X.Y version.
with open('../VERSION') as version_file:
version = version_file.read()
-
+
# The full version, including alpha/beta/rc tags.
release = version
@@ -262,3 +263,10 @@ texinfo_documents = [
# If true, do not generate a @detailmenu in the "Top" node's menu.
#texinfo_no_detailmenu = False
+
+on_rtd = os.environ.get('READTHEDOCS', None) == 'True'
+
+if not on_rtd: # only import and set the theme if we're building docs locally
+ import sphinx_rtd_theme
+ html_theme = 'sphinx_rtd_theme'
+ html_theme_path = [sphinx_rtd_theme.get_html_theme_path()]
diff --git a/docs/index.rst b/docs/index.rst
index 79167b0..e4a9ac7 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -1,4 +1,3 @@
-
kafka-python
============
@@ -49,8 +48,7 @@ Contents
install
tests
usage
- api_reference
-
+ API reference </apidoc/modules>
Indices and tables
==================
@@ -58,4 +56,3 @@ Indices and tables
* :ref:`genindex`
* :ref:`modindex`
* :ref:`search`
-
diff --git a/docs/usage.rst b/docs/usage.rst
index 5f3fcea..141cf93 100644
--- a/docs/usage.rst
+++ b/docs/usage.rst
@@ -6,7 +6,7 @@ High level
.. code:: python
- from kafka import KafkaClient, SimpleProducer, SimpleConsumer
+ from kafka import SimpleProducer, KafkaClient, KafkaConsumer
# To send messages synchronously
kafka = KafkaClient("localhost:9092")
@@ -52,7 +52,8 @@ High level
batch_send_every_t=60)
# To consume messages
- consumer = SimpleConsumer(kafka, "my-group", "my-topic")
+ consumer = KafkaConsumer("my-topic", group_id="my_group",
+ metadata_broker_list=["localhost:9092"])
for message in consumer:
# message is raw byte string -- decode if necessary!
# e.g., for unicode: `message.decode('utf-8')`
@@ -66,7 +67,8 @@ Keyed messages
.. code:: python
- from kafka import KafkaClient, KeyedProducer, HashedPartitioner, RoundRobinPartitioner
+ from kafka import (KafkaClient, KeyedProducer, HashedPartitioner,
+ RoundRobinPartitioner)
kafka = KafkaClient("localhost:9092")
diff --git a/kafka/consumer/kafka.py b/kafka/consumer/kafka.py
index ae0f0b9..cd3cc4a 100644
--- a/kafka/consumer/kafka.py
+++ b/kafka/consumer/kafka.py
@@ -57,7 +57,8 @@ class KafkaConsumer(object):
.. code:: python
# A very basic 'tail' consumer, with no stored offset management
- kafka = KafkaConsumer('topic1')
+ kafka = KafkaConsumer('topic1',
+ metadata_broker_list=['localhost:9092'])
for m in kafka:
print m
@@ -73,8 +74,10 @@ class KafkaConsumer(object):
.. code:: python
- # more advanced consumer -- multiple topics w/ auto commit offset management
+ # more advanced consumer -- multiple topics w/ auto commit offset
+ # management
kafka = KafkaConsumer('topic1', 'topic2',
+ metadata_broker_list=['localhost:9092'],
group_id='my_consumer_group',
auto_commit_enable=True,
auto_commit_interval_ms=30 * 1000,
diff --git a/setup.py b/setup.py
index 4b1e18e..f1c1954 100644
--- a/setup.py
+++ b/setup.py
@@ -1,5 +1,5 @@
import sys
-
+import os
from setuptools import setup, Command
with open('VERSION', 'r') as v:
@@ -26,6 +26,10 @@ test_require = ['tox', 'mock']
if sys.version_info < (2, 7):
test_require.append('unittest2')
+here = os.path.abspath(os.path.dirname(__file__))
+
+with open(os.path.join(here, 'README.rst')) as f:
+ README = f.read()
setup(
name="kafka-python",
@@ -46,15 +50,10 @@ setup(
url="https://github.com/mumrah/kafka-python",
license="Apache License 2.0",
description="Pure Python client for Apache Kafka",
- long_description="""
-This module provides low-level protocol support for Apache Kafka as well as
-high-level consumer and producer classes. Request batching is supported by the
-protocol as well as broker-aware request routing. Gzip and Snappy compression
-is also supported for message sets.
-""",
+ long_description=README,
keywords="apache kafka",
install_requires=['six'],
- classifiers = [
+ classifiers=[
"Development Status :: 4 - Beta",
"Intended Audience :: Developers",
"License :: OSI Approved :: Apache Software License",
@@ -62,6 +61,9 @@ is also supported for message sets.
"Programming Language :: Python :: 2",
"Programming Language :: Python :: 2.6",
"Programming Language :: Python :: 2.7",
+ "Programming Language :: Python :: 3",
+ "Programming Language :: Python :: 3.3",
+ "Programming Language :: Python :: 3.4",
"Programming Language :: Python :: Implementation :: PyPy",
"Topic :: Software Development :: Libraries :: Python Modules",
]
diff --git a/tox.ini b/tox.ini
index 71c8993..71565fd 100644
--- a/tox.ini
+++ b/tox.ini
@@ -1,5 +1,6 @@
[tox]
-envlist = lint, py26, py27, pypy, py33, py34
+envlist = lint, py26, py27, pypy, py33, py34, docs
+
[testenv]
deps =
six
@@ -37,3 +38,13 @@ deps =
mock
pylint
commands = pylint {posargs: -E kafka test}
+
+[testenv:docs]
+deps =
+ sphinxcontrib-napoleon
+ sphinx_rtd_theme
+ sphinx
+
+commands =
+ sphinx-apidoc -o docs/apidoc/ kafka/
+ sphinx-build -b html docs/ docs/_build
View Lorry Controller Status