openstack/deb-python-autobahn
Code Issues Proposed changes

work on docs

Browse Source
This commit is contained in:
Tobias Oberstein 2014-08-05 14:15:51 +02:00
parent 73ca63dfd5
commit 214b80c617
18 changed files with 284 additions and 247 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

4
autobahn/autobahn/twisted/wamp.py
View File

@ -461,7 +461,7 @@ class Application:
to subscribe to. If no URI is given, the URI is constructed from
the application URI prefix and the Python function name.
If the function yield, it will be assumed that it's an asychronous
If the function yield, it will be assumed that it's an asynchronous
process and inlineCallbacks will be applied to it.
:Example:
@ -497,7 +497,7 @@ class Application:
Signals are local events triggered internally and exposed to the
developer to be able to react to the application lifecycle.
If the function yield, it will be assumed that it's an asychronous
If the function yield, it will be assumed that it's an asynchronous
coroutine and inlineCallbacks will be applied to it.
Current signals :

16
autobahn/autobahn/wamp/interfaces.py
View File

@ -24,7 +24,7 @@ import six
@six.add_metaclass(abc.ABCMeta)
class IObjectSerializer(object):
"""
Raw Python object serialization and unserialization. Object serializers are
Raw Python object serialization and deserialization. Object serializers are
used by classes implementing WAMP serializers, that is instances of
:class:`autobahn.wamp.interfaces.ISerializer`.
"""
@ -99,8 +99,8 @@ class IMessage(object):
@abc.abstractmethod
def serialize(self, serializer):
"""
Serialize this object into a wire level bytestring representation and cache
the resulting bytestring. If the cache already contains an entry for the given
Serialize this object into a wire level bytes representation and cache
the resulting bytes. If the cache already contains an entry for the given
serializer, return the cached representation directly.
:param serializer: The wire level serializer to use.
@ -145,7 +145,7 @@ class IMessage(object):
@six.add_metaclass(abc.ABCMeta)
class ISerializer(object):
"""
WAMP message serialization and unserialization.
WAMP message serialization and deserialization.
"""
@abc.abstractproperty
@ -177,7 +177,7 @@ class ISerializer(object):
@abc.abstractmethod
def unserialize(self, bytes, isBinary):
"""
Unserializes bytes from a transport and parses WAMP messages.
Deserialize bytes from a transport and parse into WAMP messages.
:param bytes: Byte string from wire.
:type bytes: bytes
@ -217,7 +217,7 @@ class ITransport(object):
@abc.abstractmethod
def close(self):
"""
Close the transport regularily. The transport will perform any
Close the transport regularly. The transport will perform any
closing handshake if applicable. This should be used for any
application initiated closing.
"""
@ -262,7 +262,7 @@ class ITransportHandler(object):
"""
Callback fired when the transport has been closed.
:param wasClean: Indicates if the transport has been closed regularily.
:param wasClean: Indicates if the transport has been closed regularly.
:type wasClean: bool
"""
@ -368,7 +368,7 @@ class ICaller(ISession):
If the call fails, the returned Deferred/Future will be rejected with an instance
of :class:`autobahn.wamp.exception.ApplicationError`.
If the *Caller* and *Dealer* implementations support cancelling of calls, the call may
If the *Caller* and *Dealer* implementations support canceling of calls, the call may
be canceled by canceling the returned Deferred/Future.
If ``kwargs`` contains an ``options`` keyword argument that is an instance of

6
autobahn/autobahn/wamp/message.py
View File

@ -759,7 +759,7 @@ class Heartbeat(Message):
:type incoming: int
:param outgoing: Outgoing heartbeat.
:type outgoing: int
:param discard: Optional data that is discared by peer.
:param discard: Optional data that is discarded by peer.
:type discard: unicode or None
"""
assert(type(incoming) in six.integer_types)
@ -856,9 +856,9 @@ class Error(Message):
:param request_type: The WAMP message type code for the original request.
:type request_type: int
:param request: The WAMP request ID of the original request (`Call`, `Subscribe`, ...) this error occured for.
:param request: The WAMP request ID of the original request (`Call`, `Subscribe`, ...) this error occurred for.
:type request: int
:param error: The WAMP or application error URI for the error that occured.
:param error: The WAMP or application error URI for the error that occurred.
:type error: unicode
:param args: Positional values for application-defined exception.
Must be serializable using any serializers in use.

2
autobahn/autobahn/wamp/types.py
View File

@ -448,7 +448,7 @@ class CallOptions:
:param onProgress: A callback that will be called when the remote endpoint
called yields interim call progress results.
:type onProgress: a callable
:param timeout: Time in seconds after which the call should be automatically cancelled.
:param timeout: Time in seconds after which the call should be automatically canceled.
:type timeout: float
:param discloseMe: Request to disclose the identity of the caller (it's WAMP session ID)
to Callees. Note that a Dealer, depending on Dealer configuration, might

6
autobahn/autobahn/websocket/interfaces.py
View File

@ -90,7 +90,7 @@ class IWebSocketChannel(object):
:param doNotCompress: Iff ``True``, never compress this message. This only applies to
Hybi-Mode and only when WebSocket compression has been negotiated on
the WebSocket connection. Use when you know the payload
uncompressible (e.g. encrypted or already compressed).
incompressible (e.g. encrypted or already compressed).
:type doNotCompress: bool
"""
@ -142,7 +142,7 @@ class IWebSocketChannel(object):
"""
Send a message that was previously prepared with :func:`autobahn.websocket.protocol.WebSocketFactory.prepareMessage`.
:param prepareMessage: A previsouly prepared message.
:param prepareMessage: A previously prepared message.
:type prepareMessage: Instance of :class:`autobahn.websocket.protocol.PreparedMessage`.
"""
@ -238,7 +238,7 @@ class IWebSocketChannelFrameApi(IWebSocketChannel):
:type isBinary: bool
:param doNotCompress: If ``True``, never compress this message. This only applies to
Hybi-Mode and only when WebSocket compression has been negotiated on the WebSocket
connection. Use when you know the payload uncompressible (e.g. encrypted or
connection. Use when you know the payload incompressible (e.g. encrypted or
already compressed).
:type doNotCompress: bool
"""

15
autobahn/autobahn/websocket/protocol.py
View File

@ -287,7 +287,7 @@ class ConnectionRequest:
"""
Constructor.
:param peer: Descriptor of the connecting client (eg IP address/port in case of TCP transports).
:param peer: Descriptor of the connecting client (e.g. IP address/port in case of TCP transports).
:type peer: str
:param headers: HTTP headers from opening handshake request.
:type headers: dict
@ -1960,8 +1960,8 @@ class WebSocketProtocol:
When payload_len is given, it will always write that many octets to the stream.
It'll wrap within payload, resending parts of that when more octets were requested
The use case is again for fuzzing server which want to sent increasing amounts
of payload data to peers without having to construct potentially large messges
themselfes.
of payload data to peers without having to construct potentially large messages
themselves.
Modes: Hybi
"""
@ -2545,7 +2545,7 @@ class PreparedMessage:
:param doNotCompress: Iff `True`, never compress this message. This only applies to
Hybi-Mode and only when WebSocket compression has been negotiated on
the WebSocket connection. Use when you know the payload
uncompressible (e.g. encrypted or already compressed).
incompressible (e.g. encrypted or already compressed).
:type doNotCompress: bool
"""
if not doNotCompress:
@ -2641,7 +2641,7 @@ class WebSocketFactory:
:param doNotCompress: Iff `True`, never compress this message. This only applies to
Hybi-Mode and only when WebSocket compression has been negotiated on
the WebSocket connection. Use when you know the payload
uncompressible (e.g. encrypted or already compressed).
incompressible (e.g. encrypted or already compressed).
:type doNotCompress: bool
:returns: obj -- An instance of :class:`autobahn.websocket.protocol.PreparedMessage`.
@ -3496,7 +3496,7 @@ class WebSocketServerFactory(WebSocketFactory):
:type maxMessagePayloadSize: int
:param autoFragmentSize: Automatic fragmentation of outgoing data messages (when using the message-based API) into frames with payload length `<=` this size or `0` for no auto-fragmentation (default: `0`).
:type autoFragmentSize: int
:param failByDrop: Fail connections by dropping the TCP connection without performaing closing handshake (default: `True`).
:param failByDrop: Fail connections by dropping the TCP connection without performing closing handshake (default: `True`).
:type failbyDrop: bool
:param echoCloseCodeReason: Iff true, when receiving a close, echo back close code/reason. Otherwise reply with `code == 1000, reason = ""` (default: `False`).
:type echoCloseCodeReason: bool
@ -3725,8 +3725,7 @@ class WebSocketClientProtocol(WebSocketProtocol):
def createHixieKey(self):
"""
Supposed to implement the crack smoker algorithm below. Well, crack
probably wasn't the stuff they smoked - dog poo?
Implements this algorithm:
http://tools.ietf.org/html/draft-hixie-thewebsocketprotocol-76#page-21
Items 16 - 22

12
autobahn/autobahn/websocket/useragent.py
View File

@ -279,19 +279,19 @@ UA_DETECT_WS_SUPPORT_DB = {}
def lookupWsSupport(ua, debug = True):
"""
Lookup if browser supports WebSocket (Hixie76, Hybi10+, RFC6455) natively,
and if not, whether the `web-socket-js <https://github.com/gimite/web-socket-js>`_
and if not, whether the `web-socket-js <https://github.com/gimite/web-socket-js>`__
Flash bridge works to polyfill that.
Returns a tuple of booleans `(ws_supported, needs_flash, detected)` where
Returns a tuple of booleans ``(ws_supported, needs_flash, detected)`` where
* `ws_supported`: WebSocket is supported
* `needs_flash`: Flash Bridge is needed for support
* `detected` the code has explicitly mapped the support/nosupport
* ``ws_supported``: WebSocket is supported
* ``needs_flash``: Flash Bridge is needed for support
* ``detected`` the code has explicitly mapped support
:param ua: The browser user agent string as sent in the HTTP header, e.g. provided as `flask.request.user_agent.string` in Flask.
:type ua: str
:returns: tuple -- A tuple `(ws_supported, needs_flash, detected)`.
:returns: tuple -- A tuple ``(ws_supported, needs_flash, detected)``.
"""
ws = _lookupWsSupport(ua)
if debug:

28
autobahn/autobahn/websocket/utf8validator.py
View File

@ -89,10 +89,10 @@ except:
"""
Eat one UTF-8 octet, and validate on the fly.
Returns UTF8_ACCEPT when enough octets have been consumed, in which case
self.codepoint contains the decoded Unicode code point.
Returns ``UTF8_ACCEPT`` when enough octets have been consumed, in which case
``self.codepoint`` contains the decoded Unicode code point.
Returns UTF8_REJECT when invalid UTF-8 was encountered.
Returns ``UTF8_REJECT`` when invalid UTF-8 was encountered.
Returns some other positive integer when more octets need to be eaten.
"""
@ -116,13 +116,13 @@ except:
"""
Incrementally validate a chunk of bytes provided as string.
Will return a quad (valid?, endsOnCodePoint?, currentIndex, totalIndex).
Will return a quad ``(valid?, endsOnCodePoint?, currentIndex, totalIndex)``.
As soon as an octet is encountered which renders the octet sequence
invalid, a quad with valid? == False is returned. currentIndex returns
the index within the currently consumed chunk, and totalIndex the
invalid, a quad with ``valid? == False`` is returned. ``currentIndex`` returns
the index within the currently consumed chunk, and ``totalIndex`` the
index within the total consumed sequence that was the point of bail out.
When valid? == True, currentIndex will be len(ba) and totalIndex the
When ``valid? == True``, currentIndex will be ``len(ba)`` and ``totalIndex`` the
total amount of consumed bytes.
"""
##
@ -164,10 +164,10 @@ except:
"""
Eat one UTF-8 octet, and validate on the fly.
Returns UTF8_ACCEPT when enough octets have been consumed, in which case
self.codepoint contains the decoded Unicode code point.
Returns ``UTF8_ACCEPT`` when enough octets have been consumed, in which case
``self.codepoint`` contains the decoded Unicode code point.
Returns UTF8_REJECT when invalid UTF-8 was encountered.
Returns ``UTF8_REJECT`` when invalid UTF-8 was encountered.
Returns some other positive integer when more octets need to be eaten.
"""
@ -191,13 +191,13 @@ except:
"""
Incrementally validate a chunk of bytes provided as string.
Will return a quad (valid?, endsOnCodePoint?, currentIndex, totalIndex).
Will return a quad ``(valid?, endsOnCodePoint?, currentIndex, totalIndex)``.
As soon as an octet is encountered which renders the octet sequence
invalid, a quad with valid? == False is returned. currentIndex returns
the index within the currently consumed chunk, and totalIndex the
invalid, a quad with ``valid? == False`` is returned. ``currentIndex`` returns
the index within the currently consumed chunk, and ``totalIndex`` the
index within the total consumed sequence that was the point of bail out.
When valid? == True, currentIndex will be len(ba) and totalIndex the
When ``valid? == True``, currentIndex will be ``len(ba)`` and ``totalIndex`` the
total amount of consumed bytes.
"""
##

36
doc/Makefile
View File

@ -1,14 +1,21 @@
build:
scons
build_no_network:
scons --no_network
test: build
python serve.py --root ./_build --silence
test_no_network: build_no_network
python serve.py --root ./_build --silence
clean:
rm -rf _build
rm -rf _build_uploaded
rm -rf _static/img/gen
rm -rf _test
rm -rf _spelling
publish: clean build
scons publish
@ -16,10 +23,29 @@ publish: clean build
doctest:
PYTHONPATH=../autobahn sphinx-build -b doctest -v . _test
copy_css:
cp _static/css/page.css ../../AutobahnJS/doc/_static/css
cp _static/css/page.css ../../AutobahnAndroid/doc/_static/css
cp _static/css/page.css ../../AutobahnCpp/doc/_static/css
cp _static/css/page.css ../../AutobahnTestsuite/doc/_static/css
cp _static/css/page.css ../../AutobahnJS/doc/_static/css/
cp _static/css/page.css ../../AutobahnAndroid/doc/_static/css/
cp _static/css/page.css ../../AutobahnCpp/doc/_static/css/
cp _static/css/page.css ../../AutobahnTestsuite/doc/_static/css/
copy_makefile:
cp Makefile ../../AutobahnJS/doc/
cp Makefile ../../AutobahnAndroid/doc/
cp Makefile ../../AutobahnCpp/doc/
cp Makefile ../../AutobahnTestsuite/doc/
copy: copy_css copy_makefile
install_deps:
pip install -U scour
pip install -U taschenmesser
#pip install -U scons
pip install -U sphinx
pip install -U sphinx-bootstrap-theme
pip install -U pyenchant
pip install -U sphinxcontrib-spelling
pip install -U repoze.sphinx.autointerface
spelling:
PYTHONPATH=../autobahn sphinx-build -b spelling . _spelling

12
doc/SConstruct
View File

@ -51,6 +51,10 @@ os.environ['PYTHONPATH'] = '../autobahn'
taschenmesser = pkg_resources.resource_filename('taschenmesser', '..')
#taschenmesser = "../../../infrequent/taschenmesser"
AddOption('--no_network', dest = 'no_network', action = 'store_true', default = False,
help = "Run locally and disable anything doing network access")
env = Environment(tools = ['default', 'taschenmesser'],
toolpath = [taschenmesser],
ENV = os.environ)
@ -64,7 +68,13 @@ Alias("img", imgs)
## Sphinx Build
##
docs = env.Command(DOCSDIR, [], "sphinx-build -b html . $TARGET")
if GetOption('no_network'):
print("Building for no network")
docs = env.Command(DOCSDIR, [], "sphinx-build -A no_network=1 -D no_network=1 -b html . $TARGET")
else:
docs = env.Command(DOCSDIR, [], "sphinx-build -b html . $TARGET")
# sphinx-build -b spelling . _spelling
env.AlwaysBuild(docs)
Clean(docs, DOCSDIR)

21
doc/_templates/layout.html vendored
View File

@ -64,13 +64,18 @@
<img src="//d379ifj7s9wntv.cloudfront.net/reactivemanifesto/images/ribbons/we-are-reactive-black-right.png">
</a>
<script>
(function(i,s,o,g,r,a,m){i['GoogleAnalyticsObject']=r;i[r]=i[r]||function(){
(i[r].q=i[r].q||[]).push(arguments)},i[r].l=1*new Date();a=s.createElement(o),
m=s.getElementsByTagName(o)[0];a.async=1;a.src=g;m.parentNode.insertBefore(a,m)
})(window,document,'script','https://www.google-analytics.com/analytics.js','ga');
ga('create', 'UA-23019220-3', 'autobahn.ws');
ga('send', 'pageview');
</script>
{% if not no_network %}
<script>
(function(i,s,o,g,r,a,m){i['GoogleAnalyticsObject']=r;i[r]=i[r]||function(){
(i[r].q=i[r].q||[]).push(arguments)},i[r].l=1*new Date();a=s.createElement(o),
m=s.getElementsByTagName(o)[0];a.async=1;a.src=g;m.parentNode.insertBefore(a,m)
})(window,document,'script','https://www.google-analytics.com/analytics.js','ga');
ga('create', 'UA-23019220-3', 'autobahn.ws');
ga('send', 'pageview');
</script>
{% else %}
<!-- Google Analytics stripped! -->
{% endif %}
{% endblock %}

6
doc/asynchronous-programming.rst
View File

@ -151,7 +151,7 @@ In this section, we have a quick look at some of the asynchronous programming pr
Twisted Deferreds and inlineCallbacks
.....................................
Documenation pointers:
Documentation pointers:
* `Introduction to Deferreds <https://twisted.readthedocs.org/en/latest/core/howto/defer-intro.html>`__
* `Deferreds Reference <https://twisted.readthedocs.org/en/latest/core/howto/defer.html>`__
@ -295,7 +295,7 @@ Asyncio Futures and Coroutines
`Asyncio Futures <http://docs.python.org/3.4/library/asyncio-task.html#future>`_ like Twisted Deferreds encapsulate the result of a future computation. At the time of creation, the result is (usually) not yet available, and will only be available eventually.
On the other hand, asyncio futures are quite different from Twisted Deferreds. One difference is that they have no builtin machinery for chaining.
On the other hand, asyncio futures are quite different from Twisted Deferreds. One difference is that they have no built-in machinery for chaining.
`Asyncio Coroutines <http://docs.python.org/3.4/library/asyncio-task.html#coroutines>`_ are (on a certain level) quite similar to Twisted inline callbacks. Here is the code corresponding to our example above:
@ -340,7 +340,7 @@ First, consider this program using plain ``asyncio.Future``. We simulate calling
loop.run_until_complete(test())
loop.close()
Using asyncio in this way is probably uite unusual. This is becomes asyncio os opinionated towards using coroutines from the beginning. Anyway, here is what above code does:
Using asyncio in this way is probably quite unusual. This is becomes asyncio os opinionated towards using coroutines from the beginning. Anyway, here is what above code does:
1. We create a ``Future`` to be returned by our ``slow_square`` function (line 4)
2. We create a function ``resolve`` (a closure) in which we resolve the previously created Future with the result (lines 6-7)

12
doc/changelog.rst
View File

@ -27,7 +27,7 @@ Changelog
`Published <https://pypi.python.org/pypi/autobahn/0.8.10>`__
* WAMP-over-Long-poll (preliminary)
* WAMP Auth methods CR, Ticket, TOTP (preliminary)
* WAMP Authentication methods CR, Ticket, TOTP (preliminary)
* WAMP App object (preliminary)
* various fixes
@ -57,14 +57,14 @@ Changelog
* started reworking docs
* allow factories to operate without WS URL
* fix behavior on 2nd protocol violation
* fix behavior on second protocol violation
0.8.5
-----
`Published <https://pypi.python.org/pypi/autobahn/0.8.5>`__
* support WAMP endpoint/handler decorators
* new examples for endpoint/handler deorators
* new examples for endpoint/handler decorators
* fix excludeMe pubsub option
0.8.4
@ -73,7 +73,7 @@ Changelog
* initial support for WAMP v2 authentication
* various fixes/improvements to WAMP v2 implementation
* new example: WebSocket auth. with Mozilla Persona
* new example: WebSocket authentication with Mozilla Persona
* polish up documentation
0.8.3
@ -154,7 +154,7 @@ Changelog
* Twisted reactor is no longer imported on module level (but lazy)
* optimize pure Python UTF8 validator (10-20% speedup on PyPy)
* opening handshake traffic stats (per-open stats)
* add multicore echo example
* add multi-core echo example
* fixes with examples of streaming mode
* fix zero payload in streaming mode
@ -164,7 +164,7 @@ Changelog
* support latest `permessage-deflate` draft
* allow controlling memory level for `zlib` / `permessage-deflate`
* updated reference, moved docs to Readthedocs
* updated reference, moved docs to "Read the Docs"
* fixes #157 (a WAMP-CRA timing attack very, very unlikely to be exploitable, but anyway)
0.6.3

200
doc/conf.py
View File

@ -1,81 +1,38 @@
# -*- coding: utf-8 -*-
#
# Autobahn WebSockets documentation build configuration file, created by
# sphinx-quickstart on Sat Aug 13 14:17:44 2011.
#
# This file is execfile()d with the current directory set to its containing dir.
#
# Note that not all possible configuration values are present in this
# autogenerated file.
#
# All configuration values have a default; values that are commented out
# serve to show the default.
from __future__ import absolute_import
import os
import sphinx_bootstrap_theme
import sys, os
extensions = [
'sphinx.ext.autodoc',
'sphinx.ext.doctest',
'sphinx.ext.intersphinx',
'sphinx.ext.viewcode',
'sphinx.ext.ifconfig',
'sphinxcontrib.spelling'
]
try:
import sphinx_rtd_theme
except ImportError:
sphinx_rtd_theme = None
try:
from sphinxcontrib import spelling
except ImportError:
spelling = None
try:
import sphinx_bootstrap_theme
except ImportError:
sphinx_bootstrap_theme = None
# 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
# documentation root, use os.path.abspath to make it absolute, like shown here.
#sys.path.insert(0, os.path.abspath('.'))
# -- General configuration -----------------------------------------------------
# If your documentation needs a minimal Sphinx version, state it here.
#needs_sphinx = '1.0'
# Add any Sphinx extension module names here, as strings. They can be extensions
# coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
#extensions = ['sphinx.ext.autodoc']
extensions = ['sphinx.ext.autodoc',
'sphinx.ext.doctest',
'sphinx.ext.intersphinx',
'sphinx.ext.viewcode']
if spelling is not None:
extensions.append('sphinxcontrib.spelling')
spelling_lang = 'en_US'
spelling_show_suggestions = False
spelling_word_list_filename = 'spelling_wordlist.txt'
# Add any paths that contain templates here, relative to this directory.
#templates_path = ['_templates']
templates_path = ['_templates']
# The suffix of source filenames.
source_suffix = '.rst'
# The encoding of source files.
#source_encoding = 'utf-8-sig'
# The master toctree document.
master_doc = 'index'
# General information about the project.
project = u'AutobahnPython'
#copyright = u'2011-2014 <a href="http://tavendo.com">Tavendo GmbH</a>, <a href="http://creativecommons.org/licenses/by-sa/3.0/">Creative Commons CC-BY-SA</a><br>Tavendo, WAMP and "Autobahn WebSocket" are trademarks of <a href="http://tavendo.com">Tavendo GmbH</a>'
copyright = None
# The version info for the project you're documenting, acts as replacement for
# |version| and |release|, also used in various other places throughout the
# built documents.
#
base_dir = os.path.abspath(os.path.join(os.path.dirname(__file__), os.pardir, 'autobahn'))
init = {}
with open(os.path.join(base_dir, "autobahn", "__init__.py")) as f:
@ -98,38 +55,8 @@ version = release = init["__version__"]
# directories to ignore when looking for source files.
exclude_patterns = ['_build', 'work']
# The reST default role (used for this markup: `text`) to use for all documents.
#default_role = None
# If true, '()' will be appended to :func: etc. cross-reference text.
#add_function_parentheses = True
# If true, the current module name will be prepended to all description
# unit titles (such as .. function::).
#add_module_names = True
# If true, sectionauthor and moduleauthor directives will be shown in the
# output. They are ignored by default.
#show_authors = False
# The name of the Pygments (syntax highlighting) style to use.
pygments_style = 'sphinx'
#pygments_style = 'flask_theme_support.FlaskyStyle'
# pygments_style = 'pastie'
# pygments_style = 'monokai'
# pygments_style = 'colorful'
# pygments_style = 'trac'
# A list of ignored prefixes for module index sorting.
#modindex_common_prefix = []
# -- Options for HTML output ---------------------------------------------------
# The theme to use for HTML and HTML Help pages. See the documentation for
# a list of builtin themes.
## Sphinx-Bootstrap Theme
##
@ -137,6 +64,7 @@ pygments_style = 'sphinx'
##
html_theme = 'bootstrap'
html_theme_path = sphinx_bootstrap_theme.get_html_theme_path()
# (Optional) Logo. Should be small enough to fit the navbar (ideally 24x24).
# Path should be relative to the ``_static`` files directory.
html_logo = "_static/img/gen/autobahnpython.svg"
@ -206,31 +134,6 @@ html_theme_options = {
'bootstrap_version': "3",
}
# Theme options are theme-specific and customize the look and feel of a theme
# further. For a list of options available for each theme, see the
# documentation.
#html_theme_options = {}
#html_theme_options = {
# 'footertextcolor': '#ccc',
# 'sidebarbgcolor': '#111',
# 'sidebartextcolor': '#ccc',
# 'sidebarlinkcolor': '#480',
# 'relbarbgcolor': '#111',
# 'relbartextcolor': '#ccc',
# 'relbarlinkcolor': '#480',
# 'bgcolor': '#111',
# 'textcolor': '#ccc',
# 'linkcolor': '#480',
# 'headtextcolor': '#ccc',
# 'headlinkcolor': '#480',
# 'codebgcolor': '#111',
# 'codetextcolor': '#ccc',
# 'bodyfont': 'serif',
# 'headfont': 'serif',
#}
# Add any paths that contain custom themes here, relative to this directory.
#html_theme_path = []
@ -255,15 +158,24 @@ html_theme_options = {
# so a file named "default.css" will overwrite the builtin "default.css".
html_static_path = ['_static']
# additional variables which become accessible in the template engine's context for
# all pages
# html_context = {'widgeturl': 'http://192.168.1.147:8090/widget'}
## additional variables which become accessible in the template engine's
## context for all pages
##
html_context = {
'widgeturl': 'https://demo.crossbar.io/clandeckwidget'
# 'widgeturl': 'http://127.0.0.1:8090/widget'
#'widgeturl': None
#'widgeturl': 'https://demo.crossbar.io/clandeckwidget'
#'widgeturl': 'http://127.0.0.1:8090/widget'
'widgeturl': None,
'no_network': False
}
## additional variables which become accessible in RST (e.g. .. ifconfig:: not no_network)
def setup(app):
app.add_config_value('no_network', False, True)
no_network = None
# If not '', a 'Last updated on:' timestamp is inserted at every page bottom,
# using the given strftime format.
#html_last_updated_fmt = '%b %d, %Y'
@ -326,57 +238,7 @@ html_sidebars = {
htmlhelp_basename = 'AutobahnPython'
# -- Options for LaTeX output --------------------------------------------------
# The paper size ('letter' or 'a4').
#latex_paper_size = 'letter'
# The font size ('10pt', '11pt' or '12pt').
#latex_font_size = '10pt'
# Grouping the document tree into LaTeX files. List of tuples
# (source start file, target name, title, author, documentclass [howto/manual]).
latex_documents = [
('index', 'AutobahnPython.tex', u'Autobahn Python Documentation',
u'Tavendo GmbH', 'manual'),
]
# The name of an image file (relative to this directory) to place at the top of
# the title page.
#latex_logo = None
# For "manual" documents, if this is true, then toplevel headings are parts,
# not chapters.
#latex_use_parts = False
# If true, show page references after internal links.
#latex_show_pagerefs = False
# If true, show URL addresses after external links.
#latex_show_urls = False
# Additional stuff for the LaTeX preamble.
#latex_preamble = ''
# Documents to append as an appendix to all manuals.
#latex_appendices = []
# If false, no module index is generated.
#latex_domain_indices = True
# -- Options for manual page output --------------------------------------------
# One entry per manual page. List of tuples
# (source start file, name, description, authors, manual section).
man_pages = [
('index', 'autobahnpython', u'Autobahn Python Documentation',
[u'Tavendo GmbH'], 1)
]
autodoc_member_order = 'bysource'
## http://sphinx-doc.org/ext/intersphinx.html
# http://sphinx-doc.org/ext/intersphinx.html
intersphinx_mapping = {
'py': ('http://docs.python.org/', None),
#'twisted': ('http://twistedmatrix.com/documents/current/api/', None),
@ -410,3 +272,5 @@ rst_prolog = """
# http://stackoverflow.com/questions/5599254/how-to-use-sphinxs-autodoc-to-document-a-classs-init-self-method
autoclass_content = 'both'
autodoc_member_order = 'bysource'

20
doc/index.rst
View File

@ -5,12 +5,18 @@
Latest release: v\ |version| (:ref:`Changelog`)
.. raw:: html
.. ifconfig:: not no_network
<p>
<a href="https://travis-ci.org/tavendo/AutobahnPython"><img src="https://travis-ci.org/tavendo/AutobahnPython.png?branch=master" alt="Build Status" /></a>
<a href="http://pypi.python.org/pypi/autobahn"><img src="https://pypip.in/download/autobahn/badge.png" alt="Downloads" /></a>
</p>
.. raw:: html
<p>
<a href="https://travis-ci.org/tavendo/AutobahnPython">
<img src="https://travis-ci.org/tavendo/AutobahnPython.png?branch=master" alt="Build Status" />
</a>
<a href="http://pypi.python.org/pypi/autobahn">
<img src="https://pypip.in/download/autobahn/badge.png" alt="Downloads" />
</a>
</p>
-----
@ -137,7 +143,7 @@ A sample **WAMP application component** implementing all client roles:
Complete example code:
* **server**, which provides a remote procedure enpoint and publishes to a topic - `Twisted <https://github.com/tavendo/AutobahnPython/blob/master/examples/twisted/wamp/beginner/server.py>`__ - `asyncio <https://github.com/tavendo/AutobahnPython/blob/master/examples/asyncio/wamp/beginner/server.py>`__
* **server**, which provides a remote procedure endpoint and publishes to a topic - `Twisted <https://github.com/tavendo/AutobahnPython/blob/master/examples/twisted/wamp/beginner/server.py>`__ - `asyncio <https://github.com/tavendo/AutobahnPython/blob/master/examples/asyncio/wamp/beginner/server.py>`__
* **client**, which calls the procedure and subscribes to the topic - `Twisted <https://github.com/tavendo/AutobahnPython/blob/master/examples/twisted/wamp/beginner/client.py>`__ - `asyncio <https://github.com/tavendo/AutobahnPython/blob/master/examples/asyncio/wamp/beginner/client.py>`__
Introduction to WAMP Programming with |ab|:
@ -166,7 +172,7 @@ For **WAMP developers**, :doc:`wamp/programming` gives an introduction for progr
Community
---------
Development of |ab| takes place on the Github `source repository <https://github.com/tavendo/AutobahnPython>`_.
Development of |ab| takes place on the GitHub `source repository <https://github.com/tavendo/AutobahnPython>`_.
.. note::
We are open for contributions, whether that's code or documentation! Preferably via pull requests.

2
doc/installation.rst
View File

@ -77,7 +77,7 @@ And to install asyncio backports automatically when required
Install from Sources
~~~~~~~~~~~~~~~~~~~~
To install from sources, clone the repo
To install from sources, clone the repository
.. code-block:: sh

127
doc/spelling_wordlist.txt Normal file
View File

@ -0,0 +1,127 @@
Twisted
asyncio
Trollius
inlineCallbacks
Deferreds
inline
excludeMe
wxPython
Tox
CPython
stdlib
timestamp
Lua
rawsocket
serializer
subprotocol
subprotocols
Hybi
Hixie
args
kwargs
unserialized
unserialize
serializable
Testee
Jython
wallclock
walltime
mixin
Mixin
hostname
serializers
app
apps
util
wamp
WAMP
Ctor
Iff
iff
ping
pong
openHandshakeTimeout
closeHandshakeTimeout
wasClean
logOctets
logFrames
reasonUtf
sendMessage
websocket
validator
Bjoern
Hoehrmann
codepoint
currentIndex
totalIndex
websocket
xormasker
localhost
polyfill
useragent
sendPing
sendPong
sendClose
Nagle
endsOnCodePoint
Changelog
changelog
docstrings
websockify
ws
wss
slowsquare
plugin
pubsub
Peticolas
isSecure
permessage
Nagle
endsOnCodePoint
blog
backport
backports
twistd
frontend
backend
frontends
backends
setProtocolOptions
serverConnectionDropTimeout
reasonRaw
serverStatus
onConnect
namespace
unsubscribe
bzip
http
uri
longpoll
choosereactor
flashpolicy
autoimport
longpoll
chopsize
lifecycle
Lifecycle
Callees
callees
Testsuite
testsuite
Subpackages
subpath
subpaths
pongs
pings
params
unescaped
utf
acknowledgement
unregistration
unregister
unregistered
unsubscription
unsubscribe
unsubscribed
deserialization
deserialize

6
doc/websocket/programming.rst
View File

@ -56,7 +56,7 @@ So a Twisted-based echo protocol would import the base protocol from ``autobahn.
## echo back message verbatim
self.sendMessage(payload, isBinary)
while an asyncio echo protocol would import the base protocol from ``autobahn.asyncio.websocket`` and dervice from :class:`autobahn.asyncio.websocket.WebSocketServerProtocol`
while an asyncio echo protocol would import the base protocol from ``autobahn.asyncio.websocket`` and derive from :class:`autobahn.asyncio.websocket.WebSocketServerProtocol`
*asyncio:*
@ -283,7 +283,7 @@ In this callback you can do thing like
* checking the origin of the WebSocket request
* negotiate WebSocket subprotocols
For example, a WebSocket client might offer to speak several WebSocket subprotocols. The server can inspect the offered protocols in ``onConnect()`` via the supplied instance of :class:`autobahn.websocket.protocol.ConnectionRequest`. When the server accepts the client, it'll chose one of the offered subprotocols. The client can then inspect the selectec subprotocol in it's ``onConnect()`` callback in the supplied instance of :class:`autobahn.websocket.protocol.ConnectionResponse`.
For example, a WebSocket client might offer to speak several WebSocket subprotocols. The server can inspect the offered protocols in ``onConnect()`` via the supplied instance of :class:`autobahn.websocket.protocol.ConnectionRequest`. When the server accepts the client, it'll chose one of the offered subprotocols. The client can then inspect the selected subprotocol in it's ``onConnect()`` callback in the supplied instance of :class:`autobahn.websocket.protocol.ConnectionResponse`.
Connection Open
~~~~~~~~~~~~~~~
@ -383,7 +383,7 @@ So a Twisted-based protocol would import the base protocol from ``autobahn.twist
else:
print("Text message received: {0}".format(payload.decode('utf8')))
while an asyncio-based protocol would import the base protocol from ``autobahn.asyncio.websocket`` and dervice from :class:`autobahn.asyncio.websocket.WebSocketClientProtocol`
while an asyncio-based protocol would import the base protocol from ``autobahn.asyncio.websocket`` and derive from :class:`autobahn.asyncio.websocket.WebSocketClientProtocol`
*asyncio:*