refactor namespace package - docs and samples (census-instrumentation#541)

* refactor namespace package - cleanup samples

* remove wrapt from test dependencies

* remove psycopg2 from test dependencies

* remove grpcio from test dependencies

* polish README

* add badge to README

* fix typo

* add dependency link

* Revert "add dependency link"

This reverts commit 0d38883.

* polish docs

* rename Census to OpenCensus

* minor cleanup

Author: reyang

README.rst

@@ -1,16 +1,23 @@
-OpenCensus for Python - A stats collection and distributed tracing framework
-============================================================================
-
-    `Census`_ for Python. Census provides a framework to measure a server's resource
-    usage and collect performance stats. This repository contains Python related
-    utilities and supporting software needed by Census.
-
-    .. _Census: https://github.com/census-instrumentation
+OpenCensus - A stats collection and distributed tracing framework
+=================================================================
 
+|gitter|
 |circleci|
+|pypi|
 
 .. |circleci| image:: https://circleci.com/gh/census-instrumentation/opencensus-python.svg?style=shield
    :target: https://circleci.com/gh/census-instrumentation/opencensus-python
+.. |gitter| image:: https://badges.gitter.im/census-instrumentation/lobby.svg
+   :target: https://gitter.im/census-instrumentation/lobby?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge
+.. |pypi| image:: https://badge.fury.io/py/opencensus.svg
+   :target: https://pypi.org/project/opencensus/
+
+`OpenCensus`_ for Python. OpenCensus provides a framework to measure a
+server's resource usage and collect performance stats. This repository
+contains Python related utilities and supporting software needed by
+OpenCensus.
+
+.. _OpenCensus: https://github.com/census-instrumentation
 
 -  `API Documentation`_
 
@@ -74,7 +81,7 @@ You can collect traces using the ``Tracer`` `context manager`_:
     with tracer.span(name='span2') as span2:
         do_something_to_trace()
 
-Census will collect everything within the ``with`` statement as a single span.
+OpenCensus will collect everything within the ``with`` statement as a single span.
 
 Alternatively, you can explicitly start and end a span:
 
@@ -120,7 +127,7 @@ the traces are printed to stdout in JSON format. Other options include
 writing to a file, sending to Python logging, or reporting to
 Stackdriver.
 
-This example shows how to configure Census to save the traces to a
+This example shows how to configure OpenCensus to save the traces to a
 file:
 
 .. code:: python
@@ -154,7 +161,7 @@ By default, traces are exported synchronously, which introduces latency during
 your code's execution. To avoid blocking code execution, you can initialize
 your exporter to use a background thread.
 
-This example shows how to configure Census to use a background thread:
+This example shows how to configure OpenCensus to use a background thread:
 
 .. code:: python
 
@@ -235,230 +242,36 @@ For Django, you can configure the blacklist in the ``OPENCENSUS_TRACE_PARAMS`` i
 .. note:: By default, the health check path for the App Engine flexible environment is not traced,
     but you can turn it on by excluding it from the blacklist setting.
 
-Framework Integration
----------------------
-
-Census supports integration with popular web frameworks including Django,
-Flask, and Pyramid. When the application receives a HTTP request, the tracer
-will automatically generate a span context using the trace information
-extracted from the request headers and propagated to the child spans.
-
-Flask
-~~~~~
-
-In your application, use the middleware to wrap your app and the
-requests will be automatically traced.
-
-.. code:: python
-
-    from opencensus.trace.ext.flask.flask_middleware import FlaskMiddleware
-
-    app = flask.Flask(__name__)
-
-    # You can also specify the sampler, exporter, propagator in the middleware,
-    # default is using `AlwaysOnSampler` as sampler, `PrintExporter` as exporter,
-    # `GoogleCloudFormatPropagator` as propagator.
-    middleware = FlaskMiddleware(app)
-
-Django
-~~~~~~
-
-For tracing Django requests, you will need to add the following line to
-the ``MIDDLEWARE_CLASSES`` section in the Django ``settings.py`` file.
-
-.. code:: python
-
-    MIDDLEWARE_CLASSES = [
-        ...
-        'opencensus.trace.ext.django.middleware.OpencensusMiddleware',
-    ]
-
-And add this line to the ``INSTALLED_APPS`` section:
-
-.. code:: python
-
-    INSTALLED_APPS = [
-        ...
-        'opencensus.trace.ext.django',
-    ]
-
-You can configure the sampler, exporter, propagator using the ``OPENCENSUS_TRACE`` setting in
-``settings.py``:
-
-.. code:: python
-
-    OPENCENSUS_TRACE = {
-        'SAMPLER': 'opencensus.trace.samplers.probability.ProbabilitySampler',
-        'EXPORTER': 'opencensus.trace.exporters.print_exporter.PrintExporter',
-        'PROPAGATOR': 'opencensus.trace.propagation.google_cloud_format.'
-                      'GoogleCloudFormatPropagator',
-    }
-
-You can configure the sampling rate and other parameters using the ``OPENCENSUS_TRACE_PARAMS``
-setting in ``settings.py``:
-
-.. code:: python
-
-    OPENCENSUS_TRACE_PARAMS = {
-        'BLACKLIST_PATHS': ['/_ah/health'],
-        'GCP_EXPORTER_PROJECT': None,
-        'SAMPLING_RATE': 0.5,
-        'SERVICE_NAME': 'my_service',
-        'ZIPKIN_EXPORTER_HOST_NAME': 'localhost',
-        'ZIPKIN_EXPORTER_PORT': 9411,
-        'ZIPKIN_EXPORTER_PROTOCOL': 'http',
-        'JAEGER_EXPORTER_HOST_NAME': None,
-        'JAEGER_EXPORTER_PORT': None,
-        'JAEGER_EXPORTER_AGENT_HOST_NAME': 'localhost',
-        'JAEGER_EXPORTER_AGENT_PORT': 6831
-    }
-
-
-Pyramid
-~~~~~~~
-
-In your application, add the pyramid tween and your requests will be
-traced.
-
-.. code:: python
-
-    def main(global_config, **settings):
-        config = Configurator(settings=settings)
-
-        config.add_tween('opencensus.trace.ext.pyramid'
-                         '.pyramid_middleware.OpenCensusTweenFactory')
-
-To configure the sampler, exporter, and propagator, pass the instances
-into the pyramid settings
-
-.. code:: python
-
-    from opencensus.trace.exporters import print_exporter
-    from opencensus.trace.propagation import google_cloud_format
-    from opencensus.trace.samplers import probability
-
-    settings = {}
-    settings['OPENCENSUS_TRACE'] = {
-        'EXPORTER': print_exporter.PrintExporter(),
-        'SAMPLER': probability.ProbabilitySampler(rate=0.5),
-        'PROPAGATOR': google_cloud_format.GoogleCloudFormatPropagator(),
-    }
-
-    config = Configurator(settings=settings)
-
-gRPC Integration
-----------------
-
-OpenCensus provides the implementation of interceptors for both the client side
-and server side to instrument the gRPC requests and responses. The client
-interceptors are used to create a decorated channel that intercepts client
-gRPC calls and server interceptors act as decorators over handlers.
-
-gRPC interceptor is a new feature in the grpcio1.8.0 release, please upgrade
-your grpcio to the latest version to use this feature.
-
-For sample usage, please refer to the hello world example in the examples
-directory.
-
-More information about the gRPC interceptors please see the `proposal`_.
-
-.. _proposal: https://github.com/mehrdada/proposal/blob/python-interceptors/L13-Python-Interceptors.md
-
-Service Integration
--------------------
-
-Opencensus supports integration with various popular outbound services such as
-SQL packages, Requests and Google Cloud client libraries. To enable integration
-services to census:	you will need to pass the list of services to census:
-
-.. code:: python
-
-    from opencensus.trace import config_integration
-    from opencensus.trace import tracer as tracer_module
-
-    import mysql.connector
-
-    # Trace both mysql-connection and psycopg2
-    integration = ['mysql', 'postgresql']
-
-    config_integration.trace_integrations(integration)
-
-
-MySQL
-~~~~~
-
-The integration with MySQL supports the `mysql-connector`_ library and is specified
-to ``trace_integrations`` using ``'mysql'``.
-
-.. _mysql-connector: https://pypi.org/project/mysql-connector
-
-PostgreSQL
-~~~~~~~~~~
-
-The integration with PostgreSQL supports the `psycopg2`_ library and is specified
-to ``trace_integrations`` using ``'postgresql'``.
-
-.. _psycopg2: https://pypi.org/project/psycopg2
-
-
-SQLAlchemy
-~~~~~~~~~~
-
-You can trace usage of the `sqlalchemy package`_, regardless of the underlying
-database, by specifying ``'sqlalchemy'`` to ``trace_integrations``.
-
-.. _SQLAlchemy package: https://pypi.org/project/SQLAlchemy
-
-.. note:: If you enable tracing of SQLAlchemy as well as the underlying database
-    driver, you will get duplicate spans. Instead, just trace SQLAlchemy.
-
-Requests
-~~~~~~~~
-
-Census can trace HTTP requests made with the `Requests package`_. The request URL,
-method, and status will be collected.
-
-You can enable Requests integration by specifying ``'requests'`` to ``trace_integrations``.
-
-It's possible to configure a list of URL you don't want traced. By default the request to exporter
-won't be traced. It's configurable by giving an array of hostname/port to the attribute
-``blacklist_hostnames`` in OpenCensus context's attributes:
-
-.. code:: python
-
-    execution_context.set_opencensus_attr('blacklist_hostnames',['hostname:port'])
-
-Only the hostname must be specified if only the hostname is specified in the URL request.
-
-.. _Requests package: https://pypi.python.org/pypi/requests
-
-Httplib
-~~~~~~~~
-
-Census can trace HTTP requests made with the httplib library.
-
-You can enable Requests integration by specifying ``'httplib'`` to ``trace_integrations``.
-
-It's possible to configure a list of URL you don't want traced. See requests integration
-for more information. The only difference is that you need to specify hostname and port
-every time.
-
-Google Cloud Client Libraries
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-Census can trace HTTP and gRPC requests made with the `Cloud client libraries`_.
-The request URL, method, and status will be collected.
-
-You can enable Google Cloud client libraries integration by specifying ``'google_cloud_clientlibs'`` to ``trace_integrations``.
-
-.. _Cloud client libraries: https://github.com/GoogleCloudPlatform/google-cloud-python#google-cloud-python-client
-
-Threading
-~~~~~~~~~
-
-Census can propagate trace across threads when using the Threading package.
+Integration
+-----------
 
-You can enable Threading integration by specifying ``'threading'`` to ``trace_integrations``.
+OpenCensus supports integration with popular web frameworks, client libraries and built-in libraries.
+
+-  `Django`_
+-  `Flask`_
+-  `Google Cloud Client Libraries`_
+-  `gRPC`_
+-  `httplib`_
+-  `MySQL`_
+-  `PostgreSQL`_
+-  `PyMySQL`_
+-  `Pyramid`_
+-  `requests`_
+-  `SQLAlchemy`_
+-  `threading`_
+
+.. _Django: https://github.com/census-instrumentation/opencensus-python/tree/master/contrib/opencensus-ext-django
+.. _Flask: https://github.com/census-instrumentation/opencensus-python/tree/master/contrib/opencensus-ext-flask
+.. _Google Cloud Client Libraries: https://github.com/census-instrumentation/opencensus-python/tree/master/contrib/opencensus-ext-google-cloud-clientlibs
+.. _gRPC: https://github.com/census-instrumentation/opencensus-python/tree/master/contrib/opencensus-ext-grpc
+.. _httplib: https://github.com/census-instrumentation/opencensus-python/tree/master/contrib/opencensus-ext-httplib
+.. _MySQL: https://github.com/census-instrumentation/opencensus-python/tree/master/contrib/opencensus-ext-mysql
+.. _PostgreSQL: https://github.com/census-instrumentation/opencensus-python/tree/master/contrib/opencensus-ext-postgresql
+.. _PyMySQL: https://github.com/census-instrumentation/opencensus-python/tree/master/contrib/opencensus-ext-pymysql
+.. _Pyramid: https://github.com/census-instrumentation/opencensus-python/tree/master/contrib/opencensus-ext-pyramid
+.. _requests: https://github.com/census-instrumentation/opencensus-python/tree/master/contrib/opencensus-ext-requests
+.. _SQLAlchemy: https://github.com/census-instrumentation/opencensus-python/tree/master/contrib/opencensus-ext-sqlalchemy
+.. _threading: https://github.com/census-instrumentation/opencensus-python/tree/master/contrib/opencensus-ext-threading
 
 ------
  Stats

examples/trace/helloworld/django/app/__init__.py renamed to contrib/opencensus-ext-django/examples/app/__init__.py

@@ -44,7 +44,7 @@
     ],
     extras_require={},
     license='Apache-2.0',
-    packages=find_packages(exclude=('tests',)),
+    packages=find_packages(exclude=('examples', 'tests',)),
     namespace_packages=[],
     url='https://github.com/census-instrumentation/opencensus-python/tree/master/contrib/opencensus-ext-django',
     zip_safe=False,